• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

What about the little guy?

 
Ranch Hand
Posts: 815
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
So, in a few days I have the honor to rejoin the American highschool system as a Junior (now I'm revealing my age). As a self-taught programmer, I've kind of been left to my own devices to figure out Java. However, after showing some of my code to a nearby university, they've seen fit to put me in a 300 level class (not too shabby, a highschool junior taking a college junior class). However, they did have one thing to say: my commenting was abomidable. In my defense, I say my commenting was not abomidable, mearly nonexsitant. My sole comment in like 30 pages of code consitsted of "//Light it up, Biotch," before the method call which set everything rolling.

Now, All of my carreer as a programmer, I've written code for one person, the ol' Moi-memester, the Je-meister, myself. So I have no idea what needs to be commented, since I can always seem to keep track of my own code. I've since done a bit of my own fake javadocing on my Tuple2 class, so when I hold my mouse over the method call 'distanceTo(Tuple2)' in eclipse it says 'wants rectangular', while another method might say 'wants polar', or 'returns degrees'. It seems to me preposterous to comment and document every method, as some dogmas dictate, you'd have more text commented out than not.

I feel like commenting comes in to play when you're on a project with a battallion of programmers. What kind of commenting does the little guy, workin' by himself, do for commenting?

[ August 26, 2004: Message edited by: Joseph George ]
[ August 26, 2004: Message edited by: Joseph George ]
 
blacksmith
Posts: 1332
2
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I have a feeling this will get moved to another forum.

I actually got in the habit of writing what most people consider very good comments when I was on a year long project by myself. Comments should tell you what the purpose of the code is, since that's often not clear from the code itself. I find them extremely useful when going back to modify code that was written months before.
 
Ranch Hand
Posts: 1419
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Your code demonstrates _how_ things are done. Your comments should summarize the purpose of each class or method so that a maintenance programmer will know not to bother reading it if the part he needs to change lies elsewhere.

Ideally, your class and method names should provide this documentation, but sometimes clarity requires a bit moreThanAFewWords().

Ask the instructors to provide you with sample software that they consider well-commented.
 
lowercase baba
Posts: 13089
67
Chrome Java Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Even if you are working on something all by yourself, and you're the only guy who ever touches it, you need to comment it, if you are working in the professional world. Why? what happens when you quit/go on vacation/get fired/get hit by a bus? somebody then has to try and figure out all that stuff you've never documented, and it's a PAIN IN THE A**.

(guess what i've been doing for the past year???)

NOTHING annoys me more at the moment than files with comments like

// DOCUMENT THIS!!!

The previous team on my project worked on this for 1.5 years. they got laid off, and now i have to deal with a hundred-thousand lines of undocumented code.
 
Warren Dew
blacksmith
Posts: 1332
2
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
fred rosenberger:

NOTHING annoys me more at the moment than files with comments like

// DOCUMENT THIS!!!

The previous team on my project worked on this for 1.5 years. they got laid off, and now i have to deal with a hundred-thousand lines of undocumented code.


In a way, that's an encouraging sign. It used to be that people who didn't document their code had better job security. If it's changed so that the people who write comments are the ones who avoid getting laid off, that's a good thing, in my opinion.
 
author
Posts: 799
5
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Actual source I'm painfully working through is littered with comments like:



This was in the middle of a 1300-line method that was wonderfully inscrutable. Despite the voluminous comments, this code managed to provide job security for the (alleged) crackhead that wrote it. My favorites were the comments that were out and out lies. Far worse than having no comment is having an inaccurate comment.

The quality of design and code in most shops is horrid. I'm appalled at the garbage produced by people that should know better (take a look at the source for JMF, something else I'm struggling through, for another example). A coder attempting to salvage bad code with comments is like an author adding footnotes to try and explain poorly written text. Most of the time the footnotes are just as bad as the text.

Comments are a distraction from the real issue: writing code that can be maintained at low cost. If I need more than a brief class comment and an occasional explanation, then my design either sucks, my coding sucks, or both. I need to fix it.

It's really not that hard to write clean code. If people cared enough to make the effort, we wouldn't have this debate about how many comments are sufficient. Sadly, they don't. The bulk of example code out there from books, articles, open source, and production systems only sets a bad example.

Given the option of quality code with few comments or poorly crafted code with voluminous comments, your choice should be obvious.

The cynical answer to the OP's question is, of course, write as many comments as will make your team (or you) happy.

-Jeff-
 
Jeff Langr
author
Posts: 799
5
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
An example, in multiple messages. Here's the actual code, without comments, and using the exact formatting as I encountered:



Most people would agree that figuring out what's going on in parseIconsString is going to take a bit of time, particularly without some sort of helpful comments--perhaps five to ten minutes.

Next message: the source, with comments.

-Jeff-
 
Jeff Langr
author
Posts: 799
5
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Even with comments, I still find this a bit difficult to swallow. The following listing shows the comments as I found them. Note that the method comment itself is a bit of a lie. It should read something like:

// given a server, find an icon for it in the string
// "server1;icon1,server2;icon2,server3;icon3,..."



Note that this was code written for Java 1.3, so regex was not an option.

Next: a first refactoring pass.

-j-
 
Jeff Langr
author
Posts: 799
5
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
The below code isn't perfect or even optimal. What becomes important is the notion of short, simple methods that do things at one level of abstraction. Naming goes a long way. I can read the method name and have a pretty good idea of what the method should be accomplishing. If I need to understand or modify the method, I can digest it fairly quickly, in 30 seconds to a minute, instead of several minutes.

The other thing that comes out of this is that you'll start to recognize small abstractions, things that you probably do over and over in code elsewhere. You can start to genericize and extract these commonalities, further simplifying your code base. You can also recognize things that perhaps the existing Java library already does.



Next--taking advantage of the library.
 
Jeff Langr
author
Posts: 799
5
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I cheat and use 1.4 regex in this one. However, the original code wasn't written effectively enough to allow quick replacement of existing code with the split method.

This still isn't perfect but it's far more readable than the original. One might add a comment or two, but the algorithms in each method are fairly simplistic and don't need a lot of explanation.

The method isEmpty represents a fairly common need that becomes a utility method. The method findServerIconPair is also a fairly common need that you could extract to a common utility such as startsWith(String[] strings, String substring).



There's also a tiny sacrifice in efficiency that's irrelevant for this problem.

-j-
[ August 26, 2004: Message edited by: Jeff Langr ]
 
Jeff Langr
author
Posts: 799
5
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
So the final implementation is:



The StringUtil class contains the startsWith and isEmpty methods, whose implementations are simple and obvious.

Another way to go that's conceptually even more simple is to split all strings and load each server-icon pair into a Map.

The end result: compare the original method (several posts above) with the final method. The final method contains effectively four statements. An adequate Java developer should have no problem understanding these four statements in less than a minute. The body of the method needs few or no comments.

The method comment has become slightly redundant as well. The best way to eliminate that is write a set of comprehensive unit tests that demonstrates expected use of getIconForServer.

-j-
 
Jeff Langr
author
Posts: 799
5
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
And yes, I note that I'm missing a few odds and ends like trim and error handling...
 
(instanceof Sidekick)
Posts: 8791
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Back to the original question - if it's not too late.

Methods and lines of code should "express your intent", meaning names and logic are very close to how you would describe the purpose of a method to a friend. I work in a framework where work classes get values from the input, submit a request to another server, and prepare an output. It would be pretty easy to follow three lines that said almost exactly that in code. Instead I see 200-300 line methods that take all day to finger out. Anyhow, if your code expresses intent, comments are rarely necessary at low levels. There are exceptions ... as shown in the code above I'd comment the expected syntax of a string that I'm about to parse if it's not obvious. Frinstance this is in real code:


Where I do like lots of comments is on classes and packages. Package.htm is a great place to explain your larger intent, how several classes hang together, where to start reading code, how others might reuse your classes, etc. I like to pretend I'm selling shrink-wrapped packages without source, and I want my peers to enjoy using my classes. What kind of documentation would you like to read when starting up with some new utility package or API from Sun?

You might also get away with saying really good unit tests are documentation. They demonstrate creating objects and calling methods and show exactly what output is expected. Several times recently I've distributed new utility classes to the team with insructions to "Read the tests first. After all I wrote em first."
 
Warren Dew
blacksmith
Posts: 1332
2
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Jeff, I find that the biggest jump in legibility came between your first and second examples. In particular, the following comments were critical for me:



Once I know that we're talking about server/icon pairs, the rest of the code becomes far less cryptic. I think this is an excellent example of why beginning coders should put in some comments - it's easier to learn to put in a few comments than to learn good refactoring.

To me, the main advantage of the third example is that it eliminates a lot of unnecessary whitespace. I don't think it actually has fewer code lines than the original. It is better organized, but the truth is that even the original is far better than typical code I see (e.g., it has no functions longer than 100 lines).

Beyond the third example, you're taking advantage of things that weren't available to the original coder, so I don't think it's a fair comparison - though I agree it's an illustration of what can be further improved. And in real code, you couldn't just leave out a trim() that was there before, as that would introduce a bug.
 
bronco
Posts: 161
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Just one quick $0.02 comment. Javadoc is a wonderful thing...might as well use it (even if your team doesn't generate javadoc now, they might later...or you might start using an IDE that does nice things with it).

Consider:

 
Dave Wood
bronco
Posts: 161
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Bask to the original question, if you're REALLY only writing code that will NEVER been looked at by anyone else, do whatever you want.

But in the REAL WORLD, you can never assume this. Any non-trivial method should at least have method-level javadoc that explains the purpose of the method so that someone can tell from the comments what the method will do for them. Within the body of the method, comment anything that is complicated or non-obvious.

As mentioned above, class and package level comments are very useful.
 
Jeff Langr
author
Posts: 799
5
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Warren Dew:
Once I know that we're talking about server/icon pairs, the rest of the code becomes far less cryptic. I think this is an excellent example of why beginning coders should put in some comments - it's easier to learn to put in a few comments than to learn good refactoring.



Greetings Warren--

You make some good points. I agree that beginner should put in a few more comments. But to teach beginners to comment everything instead of learning to code the right way is wrong (not that you're promoting it, but many sources do). Learning good or even adequate refactoring is not at all not difficult, and I think we make a huge mistake not teaching beginning developers this from the start.

To me, the main advantage of the third example is that it eliminates a lot of unnecessary whitespace. I don't think it actually has fewer code lines than the original. It is better organized, but the truth is that even the original is far better than typical code I see (e.g., it has no functions longer than 100 lines).



The third example may even have more code lines; I didn't count. It's an incremental step toward understanding and elimination of duplication.

I find the original example typical of code out there. I don't think it's good code at all; in fact it's not acceptable on the development teams I work with.

Beyond the third example, you're taking advantage of things that weren't available to the original coder, so I don't think it's a fair comparison - though I agree it's an illustration of what can be further improved. And in real code, you couldn't just leave out a trim() that was there before, as that would introduce a bug.



Beyond the third example, the point is that proper abstracting will lead to recognition of the potential for reuse of existing or other API code. The developer that builds the original code may never even think to look for redundant abstractions. And they don't--you can find the same abstractions in dozens of other methods.

The overall point is that most code is crap, yet we put up with it. Following simple guidelines, the average system can easily be reduced in size by 30-50%. It can be simplified by a factor of five.

Given that I've done a lot of Java programming, my honest estimate to decipher a method like the original is about 3 minutes. An average developer might take 5 or more minutes. It's even more time if there is a problem in the method--five to ten minutes to break it down and run through some tests. To decipher the final result (even if I add back the split method since I can't use regex) is about a minute.

You're quibbling with respect to the trim statement. ;-)

Regards,
Jeff
 
Jeff Langr
author
Posts: 799
5
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
The tag "author" doesn't mean I don't program in the "REAL WORLD," by the way.

Putting Javadoc on everything is as bad or worse than putting it on nothing. The main value of Javadoc is to provide documentation for client use of your class, not to document implementation details.

This is randomly plucked from a class in my current client's system; it's not a class I'm intimately familiar with:



This Javadoc comment adds no value whatsoever. It only serves to clutter the code and waste my time stating something the method signature clearly states. In the shops where developers are required to write a javadoc comment for each method, this is what most of them look like. Excessive documentation wastes time.

Sure, IDEs generate most of this piffle easily.

-J-
 
Ranch Hand
Posts: 116
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Joseph George:

I feel like commenting comes in to play when you're on a project with a battallion of programmers. What kind of commenting does the little guy, workin' by himself, do for commenting?



Ok, technically, your professor at college isn't going to take that as an argument. Because you can't prove in advance your the only person ever going to be looking at "your" code. (Also, when you work for a real company, you do not own the code you write, regardless of who reads it).

But the main point I want to make, is that to score points with your professor, you should document all pre- and post conditions before a block of code, loop invariants for all loops, complex 'if' statements that have multiple lines of boolean logic, and all classes and methods. Variables should be documented with a one line description next to them when their meaning is not easily discernable from the name used. The documentation continues up the hierarchy to modules and components. Yes, it is a lot of work!

Others above me have detailed the use of javadoc, but you don't have to use that.

Always assume three people will read your code carefully;
1. A person not as smart as you
2. A person as smart as you
3. A person 10 years ahead of you in skill.

Jeff Walker
 
Warren Dew
blacksmith
Posts: 1332
2
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Jeff Langr:

I agree that beginner should put in a few more comments. But to teach beginners to comment everything instead of learning to code the right way is wrong (not that you're promoting it, but many sources do).

Agreed on that. They should learn both.

I find the original example typical of code out there. I don't think it's good code at all; in fact it's not acceptable on the development teams I work with.

Sorry, didn't mean to imply that it's good code. I should probably have said "not as atrocious as" rather than "much better than".

You're quibbling with respect to the trim statement. ;-)

A bit, yes.

However, I also think it's dangerous to say things that might come across to a beginner as, "making the code have fewer lines is more important than putting in error checking code" - I know you didn't say or mean that, but a newbie could come away with that impression.

For those of us who feel that all duplicate code should be refactored, I think it's a bit of a trap to talk about the resultant reduction in size of the code. Duplicate code should be refactored even if the result has a few more lines than the original - which I've found that it often does, at least initially, because the addition of two function calls and the function declaration, along with sometimes a new class, can be more than the number of lines removed to the function. The advantage of refactoring the duplicate code is not so much the reduction in the size of the code base, as in the centralization of the code - the fact that if the code has to be changed, or if a bug has to be fixed, the changes and fixes need only be done once rather than twice. If you or I think about that, it's obvious - but it may not be obvious to the newbie who is trying to figure out why people think refactoring is good.
 
Warren Dew
blacksmith
Posts: 1332
2
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Question regarding JavaDoc:

Last time I was on a project which parsed JavaDoc (admittedly four years ago), examples like the ones given upthread would result in scattered asterisks throughout the JavaDoc, because the line breaks would be autogenerated rather than following the original format. Generating pretty JavaDoc required cluttering up the comments with HTML tags for paragraph breaks and such.

Has that been fixed?
 
Nick George
Ranch Hand
Posts: 815
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Jeff Walker:

you should document all pre- and post conditions before a block of code, loop invariants for all loops, complex 'if' statements that have multiple lines of boolean logic, and all classes and methods. Variables should be documented with a one line description next to them when their meaning is not easily discernable from the name used.




see, that seems to me to be crazy, no offense at all intended. Thats such an astounding amount of commenting. I feel like if you're going to read code, you might have to go ahead and do a bit of thinkin'. I'm writing code here, not a novel. I refuse (at this point in my life) to document variables whose purpose 30 seconds of thought can discern, in the offchance that someone might read it at some point. Furthermore, my methods have plenty discriptive names. Method toPolar() in Tuple2 requires no documention, nor does advance(double milliseconds) in CircularThing. it advances the object milliseconds milliseconds forward!!!
 
Nick George
Ranch Hand
Posts: 815
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
see, the key here, is I don't write my code for morons.


the method's called split!



I could read that you found it, or, I could look at the if statement, which returns true if we found it.
 
Jeff Walker
Ranch Hand
Posts: 116
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Ok,
there are two kinds of documenting, what your professor will expect (to get an A+ on your assignments) and what the guy next to you in a development group will expect. What I said above about pre- and post conditions, loop invariants, etc. still holds. It is the correct way of documenting code. (Along with class descriptions and method descriptions as can be partially supplied by javadoc, etc.) It is very strict, but as I said, strict commenting does involve a lot of work. If you ever work on military projects, you will be expected to deliver strict commenting.

As for putting a comment on every line of code, (which is what is implied from the replies to my post), I did not mean that. I meant, if a variable's purpose is not discernable from its name (or function), then it needs to be documented.

Also, only 'complex' if- statements need a comment, as well as method calls.
E.g.
...
// Split it on ";"
infoVector = split(onePair, ";");
...
does not need a comment, since the operation is discernable from the method name.


But this following example does need its comment, don't you think?
// Split it on ";"
infoVector = x(onePair, ";");


One final example,
...
int a = 14;
if (((a ^ b < 2) || (b >= c/2)) && (c!= d))
...
may very well need some explaining, since the variable names are poorly chosen, and the boolean result is certainly not clear. Especially the nested parentheses and the boolean operators make it hard to read.


Now, the guy in the cube next to you is not interested in strict commenting. Few developer's could write a loop invariant anyway. What they usually want is class and method descriptions like you get from javadoc, and some comments around a whole bunch of lines telling them what each code block is doing. That usually suffices for most developers.

Remember, your code may have to go through a code review by a more experienced person, and they will pick up on your mistakes and ambiguities. If the code is too difficult to read, they will just throw it back to you on Friday afternoon, and there goes your weekend!
Jeff Walker
 
Dave Wood
bronco
Posts: 161
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Jeff Langr:
The tag "author" doesn't mean I don't program in the "REAL WORLD," by the way.


Jeff, please don't think I was directing that at you! I was going back to the original post which was from someone in high school asking about commenting code. My reference to the REAL WORLD was just meant to differentiate between writing code for yourself and writing code in a business setting.

-dave (another author who also works in the RW, FWIW)
 
Dave Wood
bronco
Posts: 161
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Warren Dew:
Question regarding JavaDoc:

Last time I was on a project which parsed JavaDoc (admittedly four years ago), examples like the ones given upthread would result in scattered asterisks throughout the JavaDoc, because the line breaks would be autogenerated rather than following the original format. Generating pretty JavaDoc required cluttering up the comments with HTML tags for paragraph breaks and such.

Has that been fixed?


The spaces I added in that example (for indentation) would not be encoded in the javadoc, but javadoc does properly remove single asterisks from the beginnings of lines (I acutally thought this had always been the case). You do need HTML to add things like paragraph tags, etc...but hopefully most methods don't need more than one paragraph to describe what they do, right? (I know, not always true, but...)
 
Jeff Langr
author
Posts: 799
5
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Dave Wood:

Jeff, please don't think I was directing that at you! I was going back to the original post which was from someone in high school asking about commenting code. My reference to the REAL WORLD was just meant to differentiate between writing code for yourself and writing code in a business setting.

-dave (another author who also works in the RW, FWIW)



Oops! ;-) thanks. I just saw the bold and reacted. Sorry about that.

-Jeff-
 
Jeff Langr
author
Posts: 799
5
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Warren Dew:
However, I also think it's dangerous to say things that might come across to a beginner as, "making the code have fewer lines is more important than putting in error checking code" - I know you didn't say or mean that, but a newbie could come away with that impression.

For those of us who feel that all duplicate code should be refactored, I think it's a bit of a trap to talk about the resultant reduction in size of the code. Duplicate code should be refactored even if the result has a few more lines than the original - which I've found that it often does, at least initially, because the addition of two function calls and the function declaration, along with sometimes a new class, can be more than the number of lines removed to the function. The advantage of refactoring the duplicate code is not so much the reduction in the size of the code base, as in the centralization of the code - the fact that if the code has to be changed, or if a bug has to be fixed, the changes and fixes need only be done once rather than twice. If you or I think about that, it's obvious - but it may not be obvious to the newbie who is trying to figure out why people think refactoring is good.



Agreed, and a good way of putting it. I'm not one to count lines of code; my chief concerns are simple design rules 2 & 3 -- no duplication and good expressiveness. I only meant to make the generalization that a reduction in code base is a good thing--if and only if the code retains or improves its readability/maintainability. (With respect to the example, I should have stated that the final small number of lines of code expresses the intent better than the original many lines of code.)

-j-

-Jeff-
 
Ranch Hand
Posts: 1923
Scala Postgres Database Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

I agree that beginner should put in a few more comments.


I would never tell a beginner that a beginner should do it like ... , because the beginner wants to act as a profi. I would try to tell him, how a profi would comment.

And you don't know his next professor, manager, team-members.
Write the comments you miss or like, when reading other peoples comments.
I agree: good variable- and method-names reduce the benefits of comments.

And you need more time to find precise names, to avoid commenting, instead of long comments.
Long comments are faster written than short, sufficient names.

I agree on the 'overview.html' where I like to put some UML-diagrams.
 
Sheriff
Posts: 7023
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Moving this to the Process forum..
 
author
Posts: 3252
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Can I recommend McConnell's Code Complete? Don't be distracted by the fact that it doesn't use Java or any other object-oriented language: I learned an awful lot from this book. Its section on commenting code is enlightening, echoes a lot of the sensible advice given above and expands considerably on it. I especially like the fact that McConnell likes to substantiate what he writes with quantitative evidence wherever available (such as quoting productivity figures when arguing that the right indentation size for a block-structured language is 3 to 4 spaces).

- Peter
 
author
Posts: 14112
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Jeff Walker:
But this following example does need its comment, don't you think?
// Split it on ";"
infoVector = x(onePair, ";");



Actually I think the code needs to be changed so that it doesn't need a comment.


One final example,
...
int a = 14;
if (((a ^ b < 2) || (b >= c/2)) && (c!= d))
...
may very well need some explaining, since the variable names are poorly chosen, and the boolean result is certainly not clear. Especially the nested parentheses and the boolean operators make it hard to read.



Again I'd prefer to improve the code. If the code is too complex to understand at first sight, I couldn't trust the comment to be right, anyway...
 
Ilja Preuss
author
Posts: 14112
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Jeff Langr:
This is randomly plucked from a class in my current client's system; it's not a class I'm intimately familiar with:



This Javadoc comment adds no value whatsoever. It only serves to clutter the code and waste my time stating something the method signature clearly states. In the shops where developers are required to write a javadoc comment for each method, this is what most of them look like. Excessive documentation wastes time.

Sure, IDEs generate most of this piffle easily.



I feel your pain. Actually, the code I am currently working on is worse:



The very first thing I do when working on a new class is deleting all the comments. They are simply worse then useless...
 
Jeff Langr
author
Posts: 799
5
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Peter den Haan:
Can I recommend McConnell's Code Complete? Don't be distracted by the fact that it doesn't use Java or any other object-oriented language:



Don't be distracted by my name in the acks either for the 2nd ed.

-j-
 
Forget this weirdo. You guys wanna see something really neat? I just have to take off my shoe .... (hint: it's a tiny ad)
a bit of art, as a gift, that will fit in a stocking
https://gardener-gift.com
reply
    Bookmark Topic Watch Topic
  • New Topic