Two Laptop Bag*
The moose likes Beginning Java and the fly likes curly braces and comments Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of OCA/OCP Java SE 7 Programmer I & II Study Guide this week in the OCPJP forum!
JavaRanch » Java Forums » Java » Beginning Java
Bookmark "curly braces and comments" Watch "curly braces and comments" New topic
Author

curly braces and comments

Daniel Rich
Greenhorn

Joined: Oct 27, 2012
Posts: 16
Hello everyone! This is more for advise than anything else. I know how to comment, I know how curly braces work also. I have my own system I follow as far as braces and comments, but I was wondering if there is a 'general standard'. A system that most (or all) programmers follow? I am a new programmer (one or two months into it) and would really like to get into good habits from the start. The way I use curly braces are as follows:



I indent my code and I can see which curly bracer belongs to what statement because I algin the closing bracer with the start of the statement.

I've seen people do it all kinds of ways. some do something like this:



and i've also seen;



What is the best pratice as far as curly bracers? If I create a program and someone else has to read it what would they expect? (i know at this level of simple programs it might not matter, but i just wanna start off on the right foot).

My next question is, just how much infomation is needed in comments? I think I'm putting to much detail in my comments, but only through fear of not putting enough. An example:



Are my comments too 'big' and is there a general rule of thumb? I know a lot of people who are helping here are proffessional programmers, would be great to hear your oppions based on your exprieance.
Marco Ehrentreich
best scout
Bartender

Joined: Mar 07, 2007
Posts: 1282

Hi Daniel,

there is an extensive list of generally accepted code conventions from Oracle/Sun which should answer a lot of questions regarding code style and which are probably followed by most Java developers who agree that it's a good idea to use a common style.

Additionally there are tools like Checkstyle which can check your source code automatically for compatibility with the common conventions. Of course all major Java IDEs (Eclipse, NetBeans, IntelliJ, ...) come with out-of-the-box support to visualize problems with your code style or even better reformat your code automatically according to pre-defined rules. Such tools can be a great help to learn how to improve your code.

For comments there is some debate if they are even necessary for well-written and readable code with good identifier names for methods, variables etc. In my personal opinion you should strive for code that can be understood by others without comments (most of the time). Comments quickly get outdated and the time to write lenghty comments should instead be invested to find better names for your identifiers, make methods smaller and improve your code in general. Of course that doesn't mean you should never use any comment if it helps to understand the code better.

Marco
Daniel Rich
Greenhorn

Joined: Oct 27, 2012
Posts: 16
Marco Ehrentreich, that is a very good point (the code been clean enough for anyone to understand without comments). I sat here reading what you said and a bulb went off over my head.


I'm using NetBeans, how would I use this 'auto formatting'? Just to get an idea of how 'it' thinks my code should look. I shall also read up on code conventions from Oracle/Sun.


I'm going to leave this topic open for a little while though, because although your advise makes perfect sense, it'll be cool to get other professionals tips.

Daniel.
Campbell Ritchie
Sheriff

Joined: Oct 13, 2005
Posts: 39478
    
  28
Warning: You will find somebody who will disagree with everything I am about to write.

No, those comments are not too big. They ought not however to have explanation of why you wrote the methods. I would suggest you ought to change them to be documentation comments. I can see a possible logic error in your setBodyType method.I would prefer to see this sort of thingYou might just possibly prefer slightly less rude descriptions
I hope you have never seen any of the three indentation conventions you quoted first, anywhere. They are none of them any good. All miss spaces where there should be spaces and have spaces where there shouldn’t be any. One of them doesn’t show any indentation at all.
We have some suggestions about formatting here. There are several differences from this style guide
  • 1: Whether you put { on a line by itself or not.
  • 2: Use of tabs/spaces.
  • 3: Tab = 4 spaces or tab = 8 spaces.
  • I suggest for the time being you always use automatic conversion of a tab to 4 spaces.
    As you will have seen I prefer to have { and } vertically aligned with each other, which allows you to see their pairings very easily, only permitting { or } as part of a line when they form parts of an array initialiser.
    I am neutral about // end comments, but they become redundant if your {} pairing is obvious. Many people have got used to having [tab]{ at the end of a line, and can see the {} pairing easily.

    Note the
    /**
     *
     */
    format for comments. The column of asterisks makes it easier to see where the comment is, particularly if the editor doesn’t highlight comments with a colour.

    Two sources about documentation comments:
  • 1: Joshua Bloch’s book Effective Java™
  • 2: This “how to” page.
  • Campbell Ritchie
    Sheriff

    Joined: Oct 13, 2005
    Posts: 39478
        
      28
    I have kept quiet about the other dubious logic I can see in your code.
    If you are using an IDE, you can usually configure it with all your preferred indentation conventions.
    Daniel Rich
    Greenhorn

    Joined: Oct 27, 2012
    Posts: 16
    Campbell Ritchie wrote:Warning: You will find somebody who will disagree with everything I am about to write.

    No, those comments are not too big. They ought not however to have explanation of why you wrote the methods. I would suggest you ought to change them to be documentation comments. I can see a possible logic error in your setBodyType method.I would prefer to see this sort of thingYou might just possibly prefer slightly less rude descriptions
    I hope you have never seen any of the three indentation conventions you quoted first, anywhere. They are none of them any good. All miss spaces where there should be spaces and have spaces where there shouldn’t be any. One of them doesn’t show any indentation at all.
    We have some suggestions about formatting here. There are several differences from this style guide
  • 1: Whether you put { on a line by itself or not.
  • 2: Use of tabs/spaces.
  • 3: Tab = 4 spaces or tab = 8 spaces.
  • I suggest for the time being you always use automatic conversion of a tab to 4 spaces.
    As you will have seen I prefer to have { and } vertically aligned with each other, which allows you to see their pairings very easily, only permitting { or } as part of a line when they form parts of an array initialiser.
    I am neutral about // end comments, but they become redundant if your {} pairing is obvious. Many people have got used to having [tab]{ at the end of a line, and can see the {} pairing easily.

    Note the
    /**
     *
     */
    format for comments. The column of asterisks makes it easier to see where the comment is, particularly if the editor doesn’t highlight comments with a colour.

    Two sources about documentation comments:
  • 1: Joshua Bloch’s book Effective Java™
  • 2: This “how to” page.


  • LOL my heart just skipped a beat. I didn't remember posting my method using ibm.. and yet you used the same variable names as me.



    LOL scary..

    Thank you Campbell, I understand what you mean and i 'felt' as though i was making my comments to 'general' and should cut to the point.
    Campbell Ritchie
    Sheriff

    Joined: Oct 13, 2005
    Posts: 39478
        
      28
    More style things about that method.
  • Call the method isMale(), call the boolean make. A enum would have been a lot better, however.
  • Use the ?: operator in preference to the inner if‑else.
  • Despite whatever the IDE wants to do, I don’t like to see keywords like else or catch surrounded by }…{ in one line. You can see that you have failed to align the }‍//close to first if with any line starts at all.
  • Campbell Ritchie
    Sheriff

    Joined: Oct 13, 2005
    Posts: 39478
        
      28
    What happens when you pass IBM = 35 to that method? I can see more logic problems.

    You should usually only quote small parts of a previous post which you are specifically replying to.
    If you persist with IBM instead of BMI, it’s IBM Inc
    Daniel Rich
    Greenhorn

    Joined: Oct 27, 2012
    Posts: 16
    Campbell Ritchie, yeah I've just now started reading about ?: operator. I've yet to put it into pratice (which is why i created this program) all the things I've learned so far without following an example used in a text book. But you've given me some ideas of what I can do better and I'm gonna jump on that today.
    Daniel Rich
    Greenhorn

    Joined: Oct 27, 2012
    Posts: 16
    Campbell Ritchie wrote:What happens when you pass IBM = 35 to that method? I can see more logic problems.

    You should usually only quote small parts of a previous post which you are specifically replying to.
    If you persist with IBM instead of BMI, it’s IBM Inc


    I'm not sure, perhaps what I should do test for the IBM (:P) and test out what you're saying. I must admitt though, it's fun to make something and go over it and see what could be better. I feel a little silly that I didn't first testDrive the IBM (i just assumed it worked). But it's a good wake up call to always check.
    Campbell Ritchie
    Sheriff

    Joined: Oct 13, 2005
    Posts: 39478
        
      28
    And what happens when you set sex=male and pass BMI=41?

    You ought to set those values in the constructor initially, using the set methods to alter the values as people eat more or starve. You do realise there is a logic error in that class having a BMI field at all? BMI is not a primary value, but is derived from the weight and height.Note that method requires two lots of comments. If you record those measurements in different units, you would have to alter the formula. The strange hieroglyphics in the comments are there because the documentation comments are converted to HTML and you want the   characters to keep the formula all on one line. I hope it prints as w / h².
    Daniel Rich
    Greenhorn

    Joined: Oct 27, 2012
    Posts: 16
    CampbellRitchie, I've glanced over your posts concerning the logic error. I agree with you that my methods 'should' be better. However, I would like to state that I never had a holistic 'idea' of what I actually wanted to do when i created this program. All I wanted to do is create an object class and set the variables using the reference operator. Then as an after thought decided create some methods to practice setters, getters and passing parameters between the main method to the object methods.



    I idea behind the BMI was simple. I decided to try and create a body type using the input I already had (height and weight). I googled if there was a way to do that and I got BMI which I throw a method together. The idea wasn't to be exact, but practice for passing two variables into it and creating a 'rough' idea of body size.



    However, I feel rather embraced now because althrough my goal was just to mess around I should have made more of an effort and not just thrown anything it together. But it does bring me to another point entirely. I was thinking (before I made this post) that it would be really good if I could make a program. I mean plan it before I even begin and with top down design really put some effort into it and have someone here (a pro) look it over and give me some feed back.



    If that some something you would be interested in (maybe)?
    Tomek Ziolkowski
    Greenhorn

    Joined: Mar 07, 2012
    Posts: 9

    I would personally suggest to avoid commenting very obvious things, for example in your code:


    a comment //An instance of a person can be avoided. Remember that you're passing information in your code mainly to other programmers (for i.e. later development of your project etc.) and for a programmer it will definitely be obvious that you're instantiating a PeopleCreation object.

    Also a code starting at line 4 should probably be a description of a class and thus should be located after import statements and before your class name signature. Comments should be in right places. You provide in your comments description of your decisions, which are not necessarily needed (you need to think whether it is actually needed in a particular place - usually it would be needed if you create a temporarily fix for a complex code and leave an information for the future that other consideration could be taken to improve this part of code later), if it is not needed then it would be better to provide short (one sentence) description of what you're doing here. If you are interested you can read about software metric 'comment density' in source files and the impact it may have on the code readability.
    Marco Ehrentreich
    best scout
    Bartender

    Joined: Mar 07, 2007
    Posts: 1282

    Hi Daniel,

    it looks like you already got A LOT of advices on how to improve your code

    This can be overwhelming at the beginning but don't let it discourage you from learning! It simply takes time - a lot of time. But you can and should make one small step after the other. Of course you're welcome to post some questions or snippets of code here but usually you can't expect anyone else to read through tons of your code and give you detailed explanations of the problems in your code as Campbell did.

    A better way to learn will surely be to use the information and tools already available which can give you thousands of hints on easy to detect code smells, design problems etc. at one simple click. As I already pointed out all modern IDEs have some kind of support for code analysis, reformatting and things like that. Depending on the IDE you will have to install some 3rd party plugins to integrate tools like Checkstyle, PMD, FindBugs, JDepend or Sonar to name a few. You can also use most of these tools without any IDE. Make yourself familiar with the features of your IDE and the said tools. Learn how to use them and what help they provide you. In most cases these tools not only show you what kind of problems there are in your code but they also give explanations why some problem really is a problem and how to improve your code. This will also improve your learning experience and you only have to post here the harder problems which can't be detected or solved by a tool

    Marco
    Marco Ehrentreich
    best scout
    Bartender

    Joined: Mar 07, 2007
    Posts: 1282

    One more thing regarding my first reply to your post:

    I wrote that comments should be avoided most of the time. I still think this is a reasonable advice for the comments scattered throughout the method and class bodies. This is true in particular for trivial comments which don't add any value like Tomek already pointed out. You should expect your code to be read by other developers who are familiar with the typical programming language features. Stating the bleeding obvious in comments doesn't help others.

    That said, there are places where good comments can be very useful. You should try to provide helpful comments for the public API of your code! Especially if you are coding some kind of library or you expect others to use your code. Then it really makes sense to add high-level comments for classes and methods which are part of the public API to describe what features your library or application provides and how the public interfaces can be used by other developers.

    Marco
    Campbell Ritchie
    Sheriff

    Joined: Oct 13, 2005
    Posts: 39478
        
      28
    You have several priorities when writing code. If you want to write code at all, I think you ought to write every line with those priorities in mind. I think your priorities are
  • 1: Correct code.
  • 2: Simple code.
  • 3: Maintainable (and extensible or enhanceable) code
  • 4: Stylish code.
  • 5: Fast code.
  • There is a lot of overlap; for example there are optimisations which will make “dumb” code run faster, as Brian Goetz points out. Usually stylish code is simple code. If you are using an object‑oriented language like Java, you should make sure to write object‑oriented code.

    A lot of us have seen lots of code over the years and can see things like the amusing results you will get from your if blocks very quickly. But on this website, we don’t tell you what is wrong. The reason is that you will remember it a lot better if you work it out for yourself.
    Daniel Rich
    Greenhorn

    Joined: Oct 27, 2012
    Posts: 16
    Marco,
    I’d just like to say, thank you. A lot of what you said made sense to me. This thread gave me huge amounts of feedback. I was a little overwhelmed with it all. However I walked away and came back after giving myself time to digest. . As far as being discouraged, no chance! I don’t expect to be a ‘hot shot’ programmer in two months flat. I do enjoy doing this and I’ve set my mind to learning java. Thank you though, for your supportive post.

    Campbell,
    I want to thank you too. At first, I must admit, I felt a little on the defensive. I had to make excuse for myself. But I understand what you were doing, and how you were helping me. Those comments about what to keep in mind while coding have been written down and stuck to screen to remind me. I’ve also re-read all your posts to take notes and test the things you pointed out so that I can fix them.

    I posted about bracers and comments, however I feel I got so much more from you two than I was expecting. You’ve both helped my mind set of programming. Thank you both, and those who posted to this thread.


    Daniel.
    Campbell Ritchie
    Sheriff

    Joined: Oct 13, 2005
    Posts: 39478
        
      28
    You’re welcome

    But what happened when you set sex=M and BMI/IBM/BIM/MIB to 43? Have you worked it out yet?
    Daniel Rich
    Greenhorn

    Joined: Oct 27, 2012
    Posts: 16
    Campbell Ritchie wrote:You’re welcome

    But what happened when you set sex=M and BMI/IBM/BIM/MIB to 43? Have you worked it out yet?


    I've not had a chance to check it yet (been busy with school stuffs), but from a glance. The answer is 'nothing' since it only goes upto or equal to 40 (40 <= ibmNumber) So perhaps I need one more if statement for anything above 40.

    Another problem I see with the code is there is nothing proventing anyone from putting height = 0 and weight = 0. So perhaps later (once i've head a chance to think it over) add some conditions to the setters that if the user puts in something 'below' what is possiable it will set it to a default height and size, or ask the user to try again. Just need to think about that carefull as far as standard heights etc.
    Campbell Ritchie
    Sheriff

    Joined: Oct 13, 2005
    Posts: 39478
        
      28
    I am pretty sure that something will happen. I also think it ain’t what you expect At least with the code you posted. You might have changed it since then.
    Marco Ehrentreich
    best scout
    Bartender

    Joined: Mar 07, 2007
    Posts: 1282

    @Daniel: You're welcome
     
    I agree. Here's the link: http://aspose.com/file-tools
     
    subject: curly braces and comments