wiki:dCacheCommunityCodingStyle
Last modified 3 years ago Last modified on 06/12/15 11:44:53

http://imgs.xkcd.com/comics/code_quality.png

dCache Community Coding Style (Proposal)

For now this is a collection of proposals in order to converge to a common coding style in the dCache community. Hopefully this will (very soon) become the dCache coding style manual.

As a starter, some docs proposed by Gerd :

  • This . document lists Java coding recommendations common in the Java development community.
  • Code Conventions for the Java Programming Language, by Sun Micro Systems.

And Gerds additions :

  • They suggest to use 2, 3, or 4 character indentation and recommend 2. Sun recommends 4. Since we already use 4, I suggest we keep using 4.
  • They suggest to but the opening curly brace of class and method definitions on a new line (but *only* for class and method definitions). Personally I prefer this style, because class and method definitions are often longer than a single line, and putting the opening brace on a new line emphasizes the block structure.
  • They recommend marking field names with an underscore. They recommend using it as a suffix, but recognize that some project use it as a prefix. Since we already use the prefix convention in dCache, I suggest we keep doing so.

Owens Additions :

  • I generally support Gerd's suggestions. and share his preferences.
  • I believe that indentation is important to be standardized, other areas (such as bracket placement) are less important.
  • I should like all (j)python to also be included in style guides. Please see URLs pep-0008 on the subject of code and pep-0257 for documentation / comments,
  • For python I wish to highlight the commandment "Never mix tabs and spaces." and "For new projects, spaces-only are strongly recommended over tabs." to facilitate this when invoking the Python command line interpreter with the -t option, it issues warnings about code that illegally mixes tabs and spaces.
  • Sh based languages are too white space sensitive for strong style guides in my opinion, but I suggest 2 spaces for bash as some times white space is significant making lines with indentation look funny when a fresh line MUST be started form the start of the line.
  • I note that some of my bash is formatted with 4 spaces, while other parts that I maintain is formatted with 2 spaces.

Vladimirs Input :

  • Vladimir essentially points out (If I may interpret his input) that coding rules are indeed just a matter of taste as they e.g. contradict between Java and Python. Vladimir would go for the Java way of doing things.
  • e.g. : exportHtmlSource(); intead of exportHTMLSource();

Dmitry did his own web page :

  • He claims :
    • I think that the style in which dCache is written is readable enough.
    • Investing time into discussions and style enforcing is a waste. (of time)
  • And his entire comments

Paul's comments:

  • As a general comment: coding style is to make code readable for humans (echoing a comment by Gerd). I think most conflict comes from balancing two conflicting influences "making the code easy to read by not having to scan through lots of waffle" and "keeping the code suitable verbose/expressive so it easy to read".
  • With the first link (Java development community), I like a lot of the recommendations. There are a few I have issues with. These are:
    • 28. I'd call these Skeleton rather than Default (if I've understood what they're talking about), as the Class may not be (in any sense) a default choice for the end-user.
    • 40. This is OK, but I prefer to have a cleaner separation between static and instance material: have the static methods before the instance fields. Also, I like to read Classes like a page from a book. In western cultures, writing tends to be top-down, so private methods tend to appear towards the end of a class.
    • 43. This is amusing rant; for consistency it's probably worth adopting the point but I can't help feeling this is something we shouldn't enforce.
    • 49. I don't think this is necessarily correct, so shouldn't be enforced.
    • 50. This is a bad example: they are trying to implement a for() loop, so it should be rewritten as such.
    • 51. Plain wrong. Yes, do-while() loops can be confusing, but the statement that they can always be rewritten as a while() or for() loop is wrong if one accepts DRY.
    • 52. NO! There's nothing wrong with continue or break; they are perfectly valid. This is an attack of Wirth-ism!
    • 53. Difficult to say in general: it may help, but it also bloats the src-code considerably, so reducing readability (screens have finite height, after all).
    • 54. Normative case first is something I try to do; however, I don't like they're braces.
    • 56. Generally yes, I agree; however I reserve the right to break this one!
    • 58. Probably a good idea, but I don't think it should be enforced.
    • 62. Agreed (my vote would be for 1.)
    • 64. Well, OK, if others want this too; I prefer methods to have the opening brace after the method declaration.
    • 65. No! It should be `} else {' as everyone (inc. Sun) knows.
    • 66. (and later) I'll probably be "boo"-ed off, but I like the single-liner (without braces)
    • 67. This is a non-issue: having an empty for() loop is inherently a mildly dangerous thing -- placing the semicolon on a separate line does not change this. Also, for consistency, shouldn't this have the braces?
    • 68. As with 66., I kinda like single-line while statements without braces.
    • 70. Spacing with switch/case statements: don't care provided each case is on its own line and the text following it is indented (relative to the 'case'). Fall-throughs should be clearly stated with a clean simple comment and should be avoided (if pos.). Also, switch() statements (or long-chain if/else/...) may indicate that the class hierarchy is broken; if possible, refactor to use polymorphism instead.
    • 71. Again, I'm with Sun: should be `} catch( ...) {' and '} finally {' each with the elements a single line.
    • 73. Nope: I doubt there's any group of more than (say) four Java programmers that agree on white-space at this level. It should be consistent within the file you're editing and, if the file is new, the format shouldn't be complete crazy.
    • 74. My style is the one they decry: doFoo( bar, baz); They only criticise it for being asymmetric, but I like that :-)
    • 76. Yeah, whatever. I think I tend to use three blank lines.
    • 78. OK, but I don't particularly like some of their examples ;-)
    • 79. Very true: code should be obvious how it works from just looking at it.
    • 83. Looks ugly to me: just use /* ... */. Trying to comment out code with comments sounds like they aren't using proper SCM software.
    • 85. WRONG, should use generics.
  • Back to general points, my recommendations:
    • if one finds oneself using switch statements, check whether the class hierarchy is OK.
    • I'd go along with Gerd's suggestion of 4 spaces for indentation (actually, I don't care that much, provided we're consistant),
    • a file should contain no tab characters (all indentation should be expressed as spaces)
    • a tab character is equivalent to eight spaces (anyone who thinks differently is confused) -- however, this doesn't matter as we shouldn't be using tabs.
    • field names should be prefixed with a _ character.
    • personally, I like classes to have the opening brace ('{') on the line following the class declaration, but all other declarations (method declarations, for, while, if, ...) to have the opening brace on the same line

as the (end of the) declaration. However, for the method declarations, the style isn't a strong feeling: I just prefer them like that.

  • when editing a file, following the existing style of the file: consistency is more important than correctness.
  • when creating a new file, we should look at the above Java Programming Style Guide for suggestions.


Last Modified by Paul @ Wed Sep 19 17:28:16 2018