Results 1 to 8 of 8
Like Tree1Likes
  • 1 Post By gimbal2

Thread: Question regarding code format/style and comments

  1. #1
    BustTheCode is offline Member
    Join Date
    Sep 2013
    Posts
    7
    Rep Power
    0

    Default Question regarding code format/style and comments

    Hi ya Java Forums,

    so I've just started getting into my major classes at school and finally taking an intro to programming course (which fortunately focuses on java). My goal before graduating is to be more than just a competent programmer. I don't want to just get a job programming and muddle through a job's expectations well enough to not get fired. I want to be a programmer companies want to recruit, write code that exceeds the expectations of my future employers, and be a reliable programmer teams are glad to have. I'm a long way off from that, so I figured I would get engaged in an online community while I'm heading in that direction.

    My questions:

    First, after doing some google searches and being unable to find decent help, I'm wondering what are some good ways to organize long, complicated equations in java to allow it to be readable and understood? For a class assignment, I had to calculate the longitude and latitude of a destination location relative to my own location with longitude and latitude. This is how I organized it (and hoping it formats correctly):

    Java Code:
    //Calculate the direction in radians
    /*------------------------------------------------------------------------ */
    /*                                                                                        */
    /*  The calculation on the double 'direction' uses the Math.atan2     */
    /*    function, and for easier viewing is divided among 3 lines.       */
    /*	                                                                                   */
    /*	Line 1 = Math.atan2 first argument                                    */
    /*	Line 2 = Math.atan2 second argument, part 1                      */
    /*	Line 3 = Math.atan2 second argument, part 2                      */
    /*  ----------------------------------------------------------------------- */		 
    				
    direction = Math.atan2( Math.sin( endLongRad - GREENLONG ) * Math.cos( endLatRad ),   //Math.atan2 arg 1 part 1
    		Math.cos( GREENLAT ) * Math.sin( endLatRad ) - Math.sin( GREENLAT )          //Math.atan2 arg 2 part 1
    		* Math.cos( endLatRad ) * Math.cos( endLongRad - GREENLONG ));               //Math.atan2 arg 2 part 2


    Second, I'm still trying to figure out when to use a comment and when not too. My teacher obviously has his own expectation, but as I've been googling and reading about commenting code, there seems to be this debate on both extremes between commenting everything, and a "less is more" approach. The latter approach, from what I've read, indicates that the code should be self evident and that comments should be used as quick explanations and/or to fill in gaps that aren't readily evident in the code itself. This philosophy (again based on what I've read, and my understanding of it) indicates that if comments have to be used for everything for the program to be understood, then there is probably an issue in clarity within the code itself.

    On the other hand, my instructor wants every variable commented on and each section of code commented on. Personally I like to comment each part of the code as a quick way to visually separate each part of the program, but it seems cumbersome to comment every variable independently when often times it seems to me that variables can be grouped together based on category. For instance, in my above program, I have the user input the longitude and latitude degrees, as well as the minutes of both longitude and latitude before converting them to radians. Since those four variables are directly connected and describing the same value, wouldn't one comment for all four work? My biggest concern with commenting is to make sure that it's done professionally in a way that employers will want to hire me regardless of my personal taste. I'm just wondering what the best practice is for commenting?

    Thanks so much to anyone who bothers reading this and replies :).
    Last edited by BustTheCode; 09-26-2013 at 03:52 PM. Reason: Edited words that weren't words

  2. #2
    KevinWorkman's Avatar
    KevinWorkman is offline Crazy Cat Lady
    Join Date
    Oct 2010
    Location
    Washington, DC
    Posts
    3,691
    Rep Power
    8

    Default Re: Question regarding code format/style and comments

    The short answer to both of your questions is that it's mostly personal preference. What one person considers completely readable might look like gibberish to somebody else, and you'll hear arguments ranging from "don't use any comments at all" to "comment every line" depending on who you ask. Do whatever seems most natural to you. To become a great programmer, you should be programming and building up a portfolio instead of making sure your code looks pretty.

    But for your first question, you might consider breaking it up into multiple lines. Can any of that long equation be taken out? As a simpler example, say I have this line, which calculates an average:

    Java Code:
    double average = (one + two + three + four + five)  / 5;
    I could perhaps make that more readable by splitting each part of the "algorithm" up into its own line:

    Java Code:
    double total = one + two + three + four + five;
    double average = total / 5;
    That's an overly simplistic example, but hopefully it demonstrates the point.

    As for commenting conventions, the golden rule is to do whatever your organization wants you to do. In your case it's your instructor, and he wants comments on every line so he can follow the thought processes of 100 different students. In other cases your employer might have coding conventions that include a comment guide. If you're coding for yourself (which is what you should be doing instead of worrying about this stuff), do whatever feels most natural to you.
    How to Ask Questions the Smart Way
    Static Void Games - Play indie games, learn from game tutorials and source code, upload your own games!

  3. #3
    Tolls is offline Moderator
    Join Date
    Apr 2009
    Posts
    11,450
    Rep Power
    19

    Default Re: Question regarding code format/style and comments

    I've noticed that for stuff that's expected to go for marking that you are expected to comment a lot more than you would in most development environments. Part of that is simply down to an expectation from the tutor that you should be able to explain everything that your code is doing.

    In real life, your code should be (to some extent) self commenting. So good naming.
    This actually fits in with your example above. I (personally) would have calculated the two parameters and stuck them in suitably named variables first, then made the call to atan2. That is a personal thing, though. I don't like to have too much happening on a single line of code...:)

    Where I find comments (again in the things I write) are really needed is in areas where stuff is complex. If I have difficulty following what I've written (or someone else, for that matter) then I'll stick some notes in. After all, odds are I'll forget why I did what I did pretty quickly.

    So don't treat what is expected of you in college as the same thing as will be expected out there in business.
    Please do not ask for code as refusal often offends.

  4. #4
    PhHein's Avatar
    PhHein is offline Senior Member
    Join Date
    Apr 2009
    Location
    Germany
    Posts
    1,430
    Rep Power
    6

    Default Re: Question regarding code format/style and comments

    For me it's "less is more". For the time being, do it the way your teacher wants it. Later your employer or customer will have some sort of guidelines, you might like or not. If I had to code/format your code it would probably look like this:
    Java Code:
    double ordinate = Math.sin( endLongRad - GREENLONG ) * Math.cos( endLatRad );
    double abscissa = Math.cos( GREENLAT ) * Math.sin( endLatRad ) - Math.sin( GREENLAT ) 
                                 * Math.cos( endLatRad ) * Math.cos( endLongRad - GREENLONG );
    
    direction = Math.atan2(ordinate, abscissa);
    EDIT: basically what Tolls wrote. Dammit, slow again.
    Math problems? Call 1-800-[(10x)(13i)^2]-[sin(xy)/2.362x]
    The Ubiquitous Newbie Tips

  5. #5
    BustTheCode is offline Member
    Join Date
    Sep 2013
    Posts
    7
    Rep Power
    0

    Default Re: Question regarding code format/style and comments

    Quote Originally Posted by KevinWorkman View Post
    The short answer to both of your questions is that it's mostly personal preference. What one person considers completely readable might look like gibberish to somebody else, and you'll hear arguments ranging from "don't use any comments at all" to "comment every line" depending on who you ask. Do whatever seems most natural to you. To become a great programmer, you should be programming and building up a portfolio instead of making sure your code looks pretty.

    But for your first question, you might consider breaking it up into multiple lines. Can any of that long equation be taken out? As a simpler example, say I have this line, which calculates an average:

    Java Code:
    double average = (one + two + three + four + five)  / 5;
    I could perhaps make that more readable by splitting each part of the "algorithm" up into its own line:

    Java Code:
    double total = one + two + three + four + five;
    double average = total / 5;
    That's an overly simplistic example, but hopefully it demonstrates the point.

    As for commenting conventions, the golden rule is to do whatever your organization wants you to do. In your case it's your instructor, and he wants comments on every line so he can follow the thought processes of 100 different students. In other cases your employer might have coding conventions that include a comment guide. If you're coding for yourself (which is what you should be doing instead of worrying about this stuff), do whatever feels most natural to you.
    Thanks for the helpful reply :). It answered all my questions/concerns and the point was well taken about coding for myself. I'm actually working on a personal project right now as we speak. Not sure I'm at a point yet in programming where any personal project would be portfolio worthy, but a strong portfolio is definitely one of my biggest concerns in regards to my overall goal (a portfolio that goes well beyond classwork).

    And in terms of the equation I used, I'm not sure if any of it can really be taken out as the instructor provided the equation and much of it is beyond my mathematical understanding at this point. I am identifying a few ways I can separate among intermediate variables though after viewing your example.

    Thanks for the help!

    EDIT:
    I got more replies than I realized while typing this response. To PhHein and Tolls, thanks for the replies :). Commenting and organization has been overwhelming me due to not knowing the "right" or "best" way to do it. I feel ten times more confident about it now.
    Last edited by BustTheCode; 09-26-2013 at 04:49 PM.

  6. #6
    gimbal2 is offline Just a guy
    Join Date
    Jun 2013
    Location
    Netherlands
    Posts
    3,083
    Rep Power
    4

    Default Re: Question regarding code format/style and comments

    There is so much good in this thread that I want to Like (with a capital), I'll just sum it all up in stead of mass-liking everything.

    Post #1, @BustTheCode. "I want to be a programmer companies want to recruit, write code that exceeds the expectations of my future employers, and be a reliable programmer teams are glad to have."
    Like!!! Although I wag the finger at "write code", you want to build solutions that exceed the expectations. In that process, writing code is but a small part of the whole.

    Post #2, @KevinWorkman. "Do whatever seems most natural to you. " Like!!!

    Post #3, @Tolls: "So don't treat what is expected of you in college as the same thing as will be expected out there in business." Like!!!
    KevinWorkman likes this.
    "Syntactic sugar causes cancer of the semicolon." -- Alan Perlis

  7. #7
    Tolls is offline Moderator
    Join Date
    Apr 2009
    Posts
    11,450
    Rep Power
    19

    Default Re: Question regarding code format/style and comments

    Group hug!
    :)
    Please do not ask for code as refusal often offends.

  8. #8
    gimbal2 is offline Just a guy
    Join Date
    Jun 2013
    Location
    Netherlands
    Posts
    3,083
    Rep Power
    4

    Default Re: Question regarding code format/style and comments

    Quote Originally Posted by Tolls View Post
    Group hug!
    :)
    Don't get me started!
    "Syntactic sugar causes cancer of the semicolon." -- Alan Perlis

Similar Threads

  1. Replies: 0
    Last Post: 09-09-2013, 11:37 AM
  2. Question about standard code style
    By lenois in forum New To Java
    Replies: 9
    Last Post: 02-08-2013, 03:56 PM
  3. Replies: 1
    Last Post: 02-21-2011, 12:33 PM
  4. How to write code comments
    By Java Tip in forum java.lang
    Replies: 0
    Last Post: 04-23-2008, 08:06 PM
  5. Comments in java code
    By lenny in forum New To Java
    Replies: 3
    Last Post: 07-25-2007, 07:59 PM

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •