Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

NX: Coding Standards

 
Michael Fitzmaurice
Ranch Hand
Posts: 168
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi all
Andrew posted the following in the never-ending thread about exposing the lock method to clients:
The "Coding Standards" is an interesting issue in it's own right - I am tempted to start a new thread just to talk about it. On second thoughts, no - someone else's turn to start theoretical topics if they want to.

Okay then, here goes...
This reminded me of some questions I wanted to ask about coding standards. In my instructions, there is no mention of adherence to any particular coding standard.
Despite the lack of an explicit instruction, I think it best to use Sun's own coding standard for this assignment. I pretty much stick to this standard all the time anyway, only with one exception, which is style of braces.
I was quite surprised to see that Sun actually include this in their standard, given its contentious nature. Personally, I prefer next line braces to end-of-line (K & R) style ones. Now, I have absolutely no intention of getting into a religious war about whether end of line is better than next line (especially since I suspect next liners like me are a minority on this one...). Sun's standard says end-of-line.
So, I can take a chance and just use my normal next line style, which means that, strictly speaking, I am not adhering to Sun's standard. How much of a risk does everyone think this is? Has anyone passed using next line braces, or anything else that breaches Sun's standard? How closely is everyone else following the standard?
Or, I could bite my coding tongue and use K & R braces (what I am actually doing is writing in my usual style, then using Jalopy & Checkstyle to reformat according to the Sun standard - this still bugs me slightly).
Opinions anyone? Anecdotal evidence? Conjecture, gossip and rumour?
 
Michael Fitzmaurice
Ranch Hand
Posts: 168
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I see
So, Mark, what made you switch to end of line (I assume this is what you now use)?
[ October 10, 2003: Message edited by: Michael Fitzmaurice ]
 
Mark Spritzler
ranger
Sheriff
Posts: 17278
6
IntelliJ IDE Mac Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I followed Sun's coding standard to a tee. When I started writing Java code, I too used the next line curly braces format and liked it so much better than the end of line style.
This is how I started.


Then I started using the end of line, but it took a while to get used to and I had trouble matching braces to each other.
Here is end of line.

But I got used to it, and I like it much better now. I mean I save a whole line.
Actually I do like how it reads better. Also I believe that the end of line thing started with "C".
But as you mention it is a preference of the coder.
But every coding standard is really a preference of the coder. Except for things like variable naming, such that you can figure out what the variable is used for, this is really a good standard that shouldn't be left to preference. That is not including some Hungarian notation naming standards of prefixes to variables to tell what type of data it stores, like int or str. This is also because in some languages, like Java, are type safe, meaning the compiler will tell you that you are trying to store an int in a String, when you compile.
Ok on that note, the purpose of standards are really so that everyone is on the same page, and everyone talks the same language. There are too many times that you have to go in and debug, maintain or enhance other programmers code. If that other person had their own standard, then you will have to spend extra time figuring some things out. Now if they all follow the same standard, then you won't have to waste that time.
On another note, standards are also a dream. I doubt we will ever have everyone following the same standards. I wish we could. I have spent a good week or so, almost rewriting one of our "fired" VB programmers code, because they didn't follow a standard, and kept Command Buttons as Command_1, Command_2, rather than cmdOK or cmdGroupSearch.
Many beginning programmers don't consider standards important. They think it is a waste of their time to follow the standard when they are coding. It takes time to make sure your namings are good, and your indentation is good, etc. But as the saying goes, pay me now or pay me much much more later.
In my years of programming, I have become more and more certain that the basics of standards are a key to great programming and helping you leave work on time and not have to spend late nights to meet a deadline.
Mark
 
Mark Spritzler
ranger
Sheriff
Posts: 17278
6
IntelliJ IDE Mac Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Michael Fitzmaurice:
I see
So, Mark, what made you switch to end of line (I assume this is what you now use)?
[ October 10, 2003: Message edited by: Michael Fitzmaurice ]

I was trying to put a "TAB" in my code, and instead it tabbed to the "Add Reply" button and I het the enter key, so it posted before I finished, hence the partial post, that I already deleted.
Mark
 
Burk Hufnagel
Ranch Hand
Posts: 814
3
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Kathy Sierra and Bert Bates wrote, in their book "Sun Certified Programmer & Developer for Java 2: Study Guide (Exam 310-035)" the following:
Another aspect of making the assessor’s life easier is what you’ll learn in Chapters 11 and 12. The little things really matter! For example, while you might think—if you indent your code four spaces—that an occasional three-space indentation here and there is OK, what’s the harm in that? The harm is in readability, and while a couple of inconsistencies in indentations might not be a big deal, adhering to the Java Coding Conventions is absolutely crucial for others looking at your code…
especially the assessor.
We’ve seen people fail the exam because they put the curly braces on the line below the method declaration rather than immediately following the declaration (on the same line), violating the official Java Coding Conventions. While this infraction alone probably might not cause you to fail, the points deducted for code convention violations might be the ones that sink you where you otherwise might have squeaked by. You don’t get to make very many mistakes in this exam. Just because your manager or your co-workers are tolerant of a little sloppiness here and there, the assessor won’t be.

I think that makes a pretty strong statement about following Sun's standards.
 
Michael Fitzmaurice
Ranch Hand
Posts: 168
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Mark
I agree completely with your comments about the need for a standard. I too know how frustrating it is to work with unintelligible spaghetti code, where classes have names like 'uPDRspd', with badly named members like 'String s', or 'int x' (or even worse, actively misleading names - I had to pick up a project here where the guy would typically do something like name a response object 'OLD_REQUEST' or a client object 'somethingorotherserver' - uggghhhhh!), and methods like 'Eqfx_PRC'. Written by a person who doesn't even name their own objects consistently, e.g. sometimes using mixed case, sometimes upper case, sometimes separating words with underscores, sometimes not, etc.
Naming conventions are especially important, and I wouldn't want to work with anyone who cannot understand this (you know the type - Mr. 'What difference does it make?').
The reason I like Jalopy & Checkstyle is that you can allow each developer to edit code in whatever format they feel comfortable with, but make sure they reformat according to whatever the standard is before checking their changes back in.
There is a default configuration in Jalopy that uses the Sun standard, so no problem there. I will conform to the standard in all my final code. Its only the braces I can't get used to right now, but I'll just force myself.
For anyone who hasn't used these (open source) tools yet, they are definitely worth a look. Plugins for most IDEs, and even ANT tasks so that you can add them to your automated build:
http://www.ociweb.com/jnb/jnbNov2002.html
Come to think of it, I wonder if the examiner runs your code through something similar to CheckStyle, in order to see how closely you adhere to the standard? It seems fairly likely.
Michael
 
Michael Fitzmaurice
Ranch Hand
Posts: 168
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I think that makes a pretty strong statement about following Sun's standards.

Agreed. I never really intended to do anything else. But, playing the role of Devil's Advocate, I might ask why Sun do not make this more explicit in their instructions?
 
Jim Yingst
Wanderer
Sheriff
Posts: 18671
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
About a year ago Kathy Sierra mentioned that they were going to make this requirement explicit in the NX version of the exam. Evidently that didn't happen. I don't know about earlier versions of the exam, but for the current version I would consider it to be extremely unfair of Sun to take off points for not following a particular standard, as this is quite simply not communicated. I don't know if they actually do still take off points; not that Kathy's comments were about past grading of the old version of the exam. And I'd have no problem with them taking off points for having an inconsistent coding style. But if they want a particular standard, they should say so. (Especially when the one included code sample, DB.java, has such abysmally poor style.)
Of course I am, indeed, following the Sun guide, just to be safe. (And it's a perfectly good style guide, with a few minor exceptions.) But the idea of graders considering it a requirement definitely rankles.
[ October 10, 2003: Message edited by: Jim Yingst ]
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 12012
216
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Everyone,
Michael I was quite surprised to see that Sun actually include [style of braces] in their standard, given its contentious nature.

But the contentious nature is the reason why they should be there! If they didn't have them in the standard, then there will always be people arguing for one style or another. This way you can stop all arguments: if the company you are working for has standardised on the Sun style, then it is explicit where the braces go.
Like Mark, I have gotten used to using braces that way (again - I originally learnt C from the K&R book, but later dropped the K&R braces style).
Michael I have absolutely no intention of getting into a religious war about whether end of line is better than next line (especially since I suspect next liners like me are a minority on this one...)

Anecdotal comment: just reading the "Exam Cram2 Java 2 Developer" book by Alain Trottier. In that book he comments that while a professor he put both styles on the board and asked students who were new to programming which they preferred - and they nearly always picked the "West Coast" style (brackets on a new line). I can certainly understand that, especially when we have to deal with the "junior programmer" who may be looking at our code.
Come to think of it, I wonder if the examiner runs your code through something similar to CheckStyle, in order to see how closely you adhere to the standard? It seems fairly likely.

I would think that there could be one of several simple tests the examiner could do:
  • Run the compiler over your code - see if there are deprecation warnings.
  • Run doccheck against your code - see if your JavaDoc meets Sun's standards
  • Run checkstyle over your code, and if there is something that doesn't match the Sun style (say braces), and if so, change that option in checkstyle and run it again - to see if your chosen style is inconsistant
  • Run jlint against your code - quick check for unreachable code and other issues


  • Jim I don't know if they actually do still take off points

    In the old Fly By Night Services assignment, "Coding Standards" was worth nearly 15% of the "General Considerations". The new assignments don't specify how "General Considerations" is broken down, but assuming the same general breakdown, that would make it worth nearly 10%. (see JavaRanch SCJD FAQ, question Has the marking changed between the old assignment and the new assignment? )
    Jim And I'd have no problem with them taking off points for having an inconsistent coding style.

    I can certainly see marks being taken off for that, and enough marks could result in a failure. Quite apart from the readability issue, too many inconsistancies would make me wonder whether the candidate did write the code, or copied and pasted other's code.
    Regards, Andrew
     
    Andrew Monkhouse
    author and jackaroo
    Marshal Commander
    Pie
    Posts: 12012
    216
    C++ Firefox Browser IntelliJ IDE Java Mac Oracle
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    For those who don't have the URL for the Sun Coding Standards documentation, here it is:
    Sun Code Conventions for the Java Programming Language
    [ October 11, 2003: Message edited by: Andrew Monkhouse ]
     
    Tony Morris
    Ranch Hand
    Posts: 1608
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    I'd have to say that I disagree with the fact that the Code Conventions for the Java Programming Language "should" be adhered to for the assignment. The requirements did not stipulate this in any way, and any experienced developer is smart enough to know that forcing coding standards such as these causes more harm than good.
    Whether or not the marker will mark down for not strictly adhering to these standards is another question. I'm a "brace on the new line" person, and I have been for nearly 15 years, in all languages. I have already submitted 12,000 lines of source code that is consistently formatted, but not strictly consistent with the Java coding conventions. I guess I'll just have to wait and see.
     
    Michael Fitzmaurice
    Ranch Hand
    Posts: 168
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Andrew This way you can stop all arguments: if the company you are working for has standardised on the Sun style, then it is explicit where the braces go.

    Quite right. My attitude to coding standards is this: if there is an applicable standard, you should follow it. To the letter (otherwise, what's the point?). If you don't like the standard, put your objections forward and try to get it changed via the agreed process. If there is no standard, create one.
    Also, when working with someone else's code, the golden rule is to be consistent with the style of the original (assuming it is actually written in a consistent style to begin with...). Even if you don't like it, and even if it contravenes the standard. Of course, if you want to reformat and rework the entire thing to conform to the standard, then that's okay too, so long as there is a consistent style.
    This is why I am feeling some slight dissonance right now - I didn't want to follow all of the standard except the parts dealing with brace style. Instead, I am following the standard to the letter. So, as far as braces go, it still feels a bit unnatural to me right now, hence the original post. It could well be that this project makes me change brace style. In fact, it probably will, since I don't want to be switching between 2 styles at work and at home, even if I can sort it all out using the various automated tools.
    As an aside to the braces point, I sometimes write scripts in Python & Jython, where the language has no braces at all. Indentation is therefore not just for readability, it actually tells the interpreter where control structures start and end. If you've never tried it, you may be surprised how natural it feels to write code this way. An no arguments about where the braces should go!
    Example:

    [ October 11, 2003: Message edited by: Michael Fitzmaurice ]
     
    Jim Yingst
    Wanderer
    Sheriff
    Posts: 18671
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    [TM]: The requirements did not stipulate this in any way
    Agreed.
    [TM]: and any experienced developer is smart enough to know that forcing coding standards such as these causes more harm than good.
    Eh? My impression is that on a big project, not having a standard does more harm than good. Most especially if some people use tabs, but don't agree on a fixed tab width. Other stuff I don't care about as much, but I'd rather see a consistent style across a project, whatever that style may be.
    The only time coding standards are a problem in my experience is when they're applied retroactively. (As may be the case here, since Sun didn't bother to tell us what they wanted.) Of course many style issues are easy to fix with a tool like jacobe. But some aren't. I once had a boss attempt to assert a new coding standard midway through a project which included the stipulation that all constants should have names like kMixedCase. :roll: Fortunately the standard also had a disclaimer in the front noting that it is often more important to match style with preexisting code than it is to follow that particular guide, and the way it was worded we were able to justify simply ignoring those parts of the code which were partuclarly inane and not easy to change automatically. Dunno if that standard ever got used in subsequent new projects at that company; I was a contractor, and moved on.
    [MF]: Also, when working with someone else's code, the golden rule is to be consistent with the style of the original (assuming it is actually written in a consistent style to begin with...).
    That's the really annoying part here - in Contractors we have a single code sample, the DB.java interface, and the "style" demonstrated by this is utterly appalling. No indentation at all. Also no javadoc comments - the API is described using // comments.
     
    Mark Spritzler
    ranger
    Sheriff
    Posts: 17278
    6
    IntelliJ IDE Mac Spring
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator

    and any experienced developer is smart enough to know that forcing coding standards such as these causes more harm than good.

    Ditto to Jim.
    After having been programming since 1977, and prgrammed in many languages, it is funny that in the past 2-3 years, I have finally came to the conclusion that forcing coding standards is a HUGE MUST. I have been involved with too many consultants and in-house programmers not following any standards and getting a huge bite in the arse, when changes and fixing bugs came down the road later.
    Mark
     
    Dave Knipp
    Ranch Hand
    Posts: 146
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    I've been discussing this topic with one of my co workers and he seems to think that sun shouldn't enforce the end of line bracing style or any kind of style as long as its consistent. I would tend to disagree for the very reason that every book thats out there on the developer exam says to adhere to sun's standards, but on the other hand everyone is right in saying that sun does not explicitly say that you should follow one bracing style or the other. So, i would just use something like jalopy to format all of your code when you are finished and are ready to submit. Just format it in sun's convention, submit it, and then change it back when you are finished if it makes you feel better For me i really have taken a liking to sun's 'eliminate white space from the face of the earth' approach so i've adopted it. What about others?
     
    Amardeep Cheema
    Greenhorn
    Posts: 17
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Hi all,
    reading the "Sun Code Conventions for the Java Programming Language" document at the link that Andrew mentioned, I came across the following confusing statement:
    4 - Indentation
    Four spaces should be used as the unit of indentation. The exact construction of the indentation (spaces vs. tabs) is unspecifed. Tabs must be set exactly every 8 spaces (not 4).

    Now how do I indent my code?
    It sounds like I am not allowed to set a Tab as 4 spaces. It must be 8. But if I then use Tabs, then I will be indenting 8 spaces each time I hit Tab (in other words, 2 units of indentation.
    The only way around this is to have a mixture of spaces and tabs. For example:
    1 unit = 4 spaces
    2 units = 1 Tab
    3 units = 1 Tab + 4 spaces
    etc
    But that sounds horrible. Do I just stick to spaces? Opinions welcome!
    Deep
     
    Bharat Ruparel
    Ranch Hand
    Posts: 493
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Hello Amardeep,
    You wrote:

    Do I just stick to spaces?

    That is what I am doing. My IDE (IntelliJ from Idea) allows me to define the tab as inserting spaces and by default, it is set to 4. It is configurable however. Most IDEs should allow you to do this.
    Regards.
    Bharat
     
    Jim Yingst
    Wanderer
    Sheriff
    Posts: 18671
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    The only way around this is to have a mixture of spaces and tabs. For example:
    1 unit = 4 spaces
    2 units = 1 Tab
    3 units = 1 Tab + 4 spaces
    etc

    Yes, this is what Sun means. According to the syle guide, if you use tabs at all, they must be used in this manner.
    But that sounds horrible. Do I just stick to spaces? Opinions welcome!
    Yes, stick to just spaces. The Sun guide also allows you to just use spaces, no tabs, and I think this is preferable since you don't have to worry about whether other coders have their tabs set correctly. As far as I know we don't actually have any evidence that Bodgett & Scarper, or URLyBird or whoever, actually are following the Sun standard. Maybe for some assignments you do; I certainly don't. So following the Sun standard is better than nothing, and a reasonable guess, but we shouldn't assume the rest of the company is following the standard; they were evidently too lazy to document it. Spaces are the safe bet. And just about any remotely decent editor will allow you to convert tabs to spaces as desribed by Bharat.
    [ October 16, 2003: Message edited by: Jim Yingst ]
     
    Amardeep Cheema
    Greenhorn
    Posts: 17
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Thanks for the feedback fellas. I will use spaces everywhere.
    By the way, I am using Eclipse with the Jalopy plug-in, and about to switch to Checkstyle. Eclipse is really great - the first Java IDE I've come across which I actually prefer over a simple text editor.
    Deep
     
    • Post Reply
    • Bookmark Topic Watch Topic
    • New Topic