# Question regarding code format/style and comments

• 09-26-2013, 03:46 PM
BustTheCode
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):

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 :).
• 09-26-2013, 04:27 PM
KevinWorkman
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:

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:

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.
• 09-26-2013, 04:30 PM
Tolls
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.
• 09-26-2013, 04:35 PM
PhHein
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:
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.
• 09-26-2013, 04:42 PM
BustTheCode
Re: Question regarding code format/style and comments
Quote:

Originally Posted by KevinWorkman
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:

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:

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.
• 09-26-2013, 05:34 PM
gimbal2
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!!!
• 09-26-2013, 06:08 PM
Tolls
Re: Question regarding code format/style and comments
Group hug!
:)
• 09-27-2013, 09:06 AM
gimbal2
Re: Question regarding code format/style and comments
Quote:

Originally Posted by Tolls
Group hug!
:)

Don't get me started!