Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

What was the strangest coding standard rule that you were forced to follow?

stackoverflow.com

Post reply on HN
Print view View original

61–70 of 83 posts

Re: What was the strangest coding standard rule that you were forced to follow?

#61

Post by wladimir »

afandian wrote: post #45
Deestan wrote: post #26

Not so much strange, as Twilight Zone-esque insane: All methods and properties must be commented with XML . Sounds like a good idea, until you see how this turns terse and readable code into a bag of chatty noise. Basically this: public enum ConnectionState { Disconnected, Connecting, Connected } Was not compliant ("There's no comments! It's not readable!"), while this: /// /// The Connection State. /// public enum C…

I too was forced to do that. I too found it ridiculous. But not for long. There was a utility for generating the documentation strings (it got them right most of the time) and there's a lot to be said for consistency, even if it produces the occasional pointless-looking artefact. The reason this requirement is in the C# style guidelines is because it gives a consistent way of commenting and, of course, allows extract…

But why XML? IMO the doxygen / javadoc style of comments makes for much less pollution. XML is not a good format for text that is to be read by humans.

Re: What was the strangest coding standard rule that you were forced to follow?

#62

Post by contingencies »

The company must scale! Sysadmin and webdev must be split! Therefore all (junior, barely unix-aware) web developers must provide automated Freebsd-specific install, test, start and stop scripts in a custom and ill-considered package format with no inter-component runtime or instllation-time dependency support. For every project. Therefore the perlmonger in charge and sysadmin extraordinaire can automate their dabblings.

Needless to say, getting barely PHP capable people who'd heard of unix to automate dependency installation and maintenance on such a platform didn't work out well. Did I mention this was 2010?

Re: What was the strangest coding standard rule that you were forced to follow?

#63

Post by samuellb »

lmm wrote: post #51
mseebach wrote: post #38

Earlier quoted context omitted.

I mostly agree, although I'd like to enhance the bit in point 3 and 4 about only ever reformatting code you're actually working on - meaning, you take responsibility for any code that your autoformatter changes is just as readable as before. Changing the name of a constant on line three doesn't give you license to autoformat the rest of the file.

I think it does. Carefully maintained manual formatting takes too much programmer effort. If you open a file to actually work on, you should be permitted to hit the autoformat button without thinking, because then formatting becomes something you just don't think about. It's not as good as good manual formatting, but it's good enough, and frees up mental resources for more important things.

I'd say this depends on the project and the developers. In some projects reading code is done a lot more often (and by more people) than actually writing code, so then you might want to spend more time on e.g. formatting, documenting, etc..

Re: What was the strangest coding standard rule that you were forced to follow?

#64

Post by wlue »

I worked at a start-up whose engineering lead brought familiar coding style to a project that was inherited. We were imposed a combination of C89-esque and Microsoft kernel coding style on an Objective-C source code. Things like defining all variables at the beginning of the function definition in alphabetical order in CamelCase, having instance variables prefixed with the class abbreviation, and other inane rules. It went something like this:

  - (void)
  doSomethingOnObjectAndNumber:
    (NSObject *) MyObject :
    (NSInteger) MyNumber
  
  /*++
  Some unstandard doc format.
  --*/

  {
    
    ...
    return;
  }
Before I started, I was told that the project migrated from git to svn to "make branching easier". I do not work there any more.

Re: What was the strangest coding standard rule that you were forced to follow?

#65

Post by ygra »

josh_fyi wrote: post #29
unimpressive wrote: post #5

I was talking to someone today, and they commented: "Good programmers eventually learn to misspell words like void or int so that they can name their variable names what they want to name them." I of course told him that this was terrible advice, and would mess with the next person who had to maintain the code because you couldn't tell at a glance if a word was a keyword or a keyword mispelled. I asked him what langu…

klass for a variable of type Class is totally normal in Java.

Isn't it usually clazz?

But such things are quite annoying for automatic code generators, though, as they have to make sure that they won't ever emit an identifier that clashes with a keyword. The ability to just prepend @ in C# is quite helpful in that regard.

Re: What was the strangest coding standard rule that you were forced to follow?

#66

Post by ygra »

wladimir wrote: post #61
afandian wrote: post #45

Earlier quoted context omitted.

I too was forced to do that. I too found it ridiculous. But not for long. There was a utility for generating the documentation strings (it got them right most of the time) and there's a lot to be said for consistency, even if it produces the occasional pointless-looking artefact. The reason this requirement is in the C# style guidelines is because it gives a consistent way of commenting and, of course, allows extract…

But why XML? IMO the doxygen / javadoc style of comments makes for much less pollution. XML is not a good format for text that is to be read by humans.

Javadoc is tied so closely to HTML that any output format other than HTML is quite difficult to achieve.

Re: What was the strangest coding standard rule that you were forced to follow?

#67

Post by afandian »

bruceboughton wrote: post #57
afandian wrote: post #50

Earlier quoted context omitted.

Not sure what you mean by "the API". You mean C# interfaces? And what about Intellisense?

Intellisense is generated from the types, methods, fields, and properties (the API). If there is XML documentation it is added to Intellisense popup. If the documentation is auto-generated from the code structure then it will add nothing that is not already present in the Intellisense.

Sure. Like I said, there are some cases where the textual documentation adds nothing to the stuff it's derived from. And there are lots of cases where documentation is useful (I'm assuming you're not saying there should be no documentation). I think that it's worth having consistency of rules (with some redundancy) over patchy documentation. I'm not trying to convince anyone, just a datapoint that I don't think it's "insane".

Re: What was the strangest coding standard rule that you were forced to follow?

#68

Post by afandian »

Deestan wrote: post #56
afandian wrote: post #45

Earlier quoted context omitted.

I too was forced to do that. I too found it ridiculous. But not for long. There was a utility for generating the documentation strings (it got them right most of the time) and there's a lot to be said for consistency, even if it produces the occasional pointless-looking artefact. The reason this requirement is in the C# style guidelines is because it gives a consistent way of commenting and, of course, allows extract…

There wasn't "the occasional pointless-looking artifact"; I would have been fine with that. 95% of all code comments merely mimicked the type signature. People were using Visual Studio plugins to autogenerate the "documentation". Pressing SHIFT+ALT+J (or something) would read the function name and type signature and regurgutate some XML doc matching it. > allows extraction of documentation and intellisense. These alr…

Fair enough. I found that in a collaborative environment (people making and sharing code) the style guidelines had a net positive effect (and believe me, my first gut reaction was along the 'this is insane' lines). As process go, the degree of automation and strict automatic enforcement (and fixing) of rules felt lightweight after a bit.

We're neither of us going to convince the other, I just thought I'd add a datapoint. FWIW I now write Python and although PEP8 isn't as hard-line, I think it similarly does a lot of good.

Re: What was the strangest coding standard rule that you were forced to follow?

#69

Post by ygra »

afandian wrote: post #67
bruceboughton wrote: post #57

Earlier quoted context omitted.

Intellisense is generated from the types, methods, fields, and properties (the API). If there is XML documentation it is added to Intellisense popup. If the documentation is auto-generated from the code structure then it will add nothing that is not already present in the Intellisense.

Sure. Like I said, there are some cases where the textual documentation adds nothing to the stuff it's derived from. And there are lots of cases where documentation is useful (I'm assuming you're not saying there should be no documentation). I think that it's worth having consistency of rules (with some redundancy) over patchy documentation. I'm not trying to convince anyone, just a datapoint that I don't think it's…

The original point was that auto-generated documentation comments contain nothing that isn't already there in the public interface. Since it tends to look like

    /**
     * Foos the bar.
     *
     * @param bar The bar.
     */
    public void fooBar(Bar bar) { ... }
The problem with this kind is that the compiler can no longer warn about a missing documentation comment because from its side all looks nice and well – except that there is zero information in that documentation.

My boss once did that to our entire codebase, adding auto-generated doc comments where there weren't any. Sure, my warning count reached a new low, but documentation quality suffered for months.

Re: What was the strangest coding standard rule that you were forced to follow?

#70

Post by afandian »

wladimir wrote: post #61
afandian wrote: post #45

Earlier quoted context omitted.

I too was forced to do that. I too found it ridiculous. But not for long. There was a utility for generating the documentation strings (it got them right most of the time) and there's a lot to be said for consistency, even if it produces the occasional pointless-looking artefact. The reason this requirement is in the C# style guidelines is because it gives a consistent way of commenting and, of course, allows extract…

But why XML? IMO the doxygen / javadoc style of comments makes for much less pollution. XML is not a good format for text that is to be read by humans.

It's been a while so I'm a bit rusty. But for most comments it would just be a start and end tag. You could also reference other types, XHTML style.
Post reply on HN