5 ms·
I tend to get a bit upset if code has comments that basically just describe what code is doing rather than why. Stuff along the lines of: // Increment the t
by arethuza 14y ago
I tend to get a bit upset if code has comments that basically just describe what code is doing rather than why. Stuff along the lines of:
// Increment the total
total++;
// Execute our SQL query
var result = query.execute();
Seems to happen a lot with developers who use comments to "sketch out" code (not a bad thing) and then leave the comments in place when the actual code is written.
- flatline3 14y agoI prefer code where I can skim the comments and see the major plot points, at a glance.
- dllthomas 14y agoIf you need to skim the comments to see how a function is doing what it's doing, the function is too long.
- flatline3 14y agoWhen it can take 3-4 statements to perform a single logical operation, there is still value in summarizing each block with a comment, even if the function isn't "too long".
- gnaritas 14y agoThat's what function names are for. Comments don't need to summarize. A useful comments says why code is this way, it doesn't summarize or repeat code.
- flatline3 14y ago> That's what function names are for. A single function for every 3-4 line operation would result in incredibly disjointed code, and would require more explicit documentation of invariants because that function can now be called elsewhere (at least inside of the given translation unit). > A useful comments says why code is this way, it doesn't summarize or repeat code. That's nonsensical. Why wouldn't you want to abstract the complex?
- gnaritas 14y agoI abstract code with code, not with comments. Comments in general stink, and are used to express what code can't. If I can express it in code, it doesn't need a comment. Every comment is a sign that you failed to write expressive code. If you need a comment to say what the next four lines do, you need a function for that, not a comment.
- flatline3 14y agoFunctions have maintenance and implementation overhead. They define an API that is accessible from the translation unit, and they thus require defining some amount of invariants. They also require breaking flow from the current function being implemented to hoist the code upwards. A short, atomic unit of 4-6 lines of code does not deserve to be a function simply because it's an atomic unit, but it does warrant a simple comment that someone skimming the code can use as an index to determine where they want to look. It's all about making the code approachable in bite size pieces for future maintainers, your collaborators, and your future self. Breaking it into pieces and describing the code means that maintainers are not required to trace out all the code and swap in a huge amount of knowledge just to determine what a given function does, and why, and what is safe to change within it.
- gnaritas 14y ago> A short, atomic unit of 4-6 lines of code does not deserve to be a function simply because it's an atomic unit And I couldn't disagree more with that statement, and virtually everything you've said. Maintainers don't need to look at a function to see what it does, that's what its name tells you and keeping functions focused on doing one atomic thing is what allows the name to replace the implementation and makes for well written programs. I despise programs written in the style you suggest. A well written program is a thousand small functions/methods unburdened by long methods full of comments. Good code requires few comments other than those that explain implementation choices or class responsibilities. Comments are a code smell most of the time, they exist to make up for poorly written code.
- barrkel 14y agoMaybe the compiler needs to see the whole function in order to properly optimize register usage, because the function is on the critical path. There is sometimes more to code than readability, unfortunately. I have worked with functions thousands of lines long that can't be broken up without losing a few percentage points of speed - but these functions are called millions of times.
- LiveTheDream 14y agoEffective use of macros or inlining could solve that problem.
- barrkel 14y agoOver 2,000 lines with macros. Inlining didn't give good enough results (at the time).
- dllthomas 14y agoIt's always a matter of heuristics, for sure. When you need to modify code in a way that's less than readable/obvious, then you start dropping in comments to compensate. Your first pass should be understandable and obvious and readable, with comments typically restricted to documenting functions and interfaces.
- arethuza 14y agoYou would actually write an "Increment the total" comment?
- flatline3 14y agoThat example is rather hyperbolic and not particularly useful. I can't recall the last time in 15 years that I thought "this code has too many comments!"
- gms7777 14y agoBack in college I was a teaching assistant for CS classes and graded a lot of what was very often very poorly written and majorly undercommented code. But I do remember once getting an incredibly unnecessary 2 page long comment for a 10 line function. That may be the only time that thought has gone through my head. At my first internship, the code base had basically no comments in it, but was in general very clean, very organized, and there was a ton of thought put into naming and organization for readability. It was a good exercise for me working like that because it forced me to not rely on comments to explain messy code. But I also remember having long debates about what to name a variable to make it perfectly clear to the next person reading this code what it does (and often times ending up with excessively long variable names) and thinking "wow...this is a waste of time. You could just add a 1 line comment"
- arethuza 14y ago"I can't recall the last time in 15 years that I thought "this code has too many comments!"" I've thought that every time I see a source file that contains an automatically generated header built from the revision history.
- dahvyd 14y agoConsider the standard Java cough paradigm used by multitudes of developers, and on by default in many Java IDEs: /* Gets the person's name @returns the person's name */ public String getName() { return name; } That is insane. The comment adds nothing to anyone's day and helps no one better understand the method than after simply reading the method signature.
- theorique 14y agoyou can get even crazier if you add in plenty of spurious logging # print out the value of x prior to increment print("x value prior to increment: %d" % x) # increment the value of x x += 1 # print out the value of x after increment by one print("x value after increment by one: %d" % x)
- arethuza 14y agoI've seen quite a lot of code that kind of looks like this: // Increment the total log.Debug("total before increment=" + total); total++; log.Debug("total after increment=" + total); I find myself looking at it and going where is stuff actually happening! I sort of wish someone would allow comments and logging to be combined as language features.
- theorique 14y agoHm, my code didn't format as intended. What you wrote is what I meant.
- einhverfr 14y agoThe typical case where this happens is that the logging was added because of some bug somewhere and this was put in place to figure out what was going on with total. See it as an archaeological record more than anything else ;-)
- throwaway-864 14y agoCheck out Smart::Comments module in Perl [1]. It allows the specially-formatted comments to produce debugging output. From the synopsis: use Smart::Comments; my $var = suspect_value(); ### $var ### got: $var ### Now computing value... # and when looping: for my $big_num (@big_nums) { ### Factoring... done factor($big_num); } while ($error > $tolerance) { ### Refining---> done refine_approximation() } for (my $i=0; $i<$MAX_INT; $i++) { ### Working===[%] done do_something_expensive_with($i); } [1] https://metacpan.org/module/Smart::Comments https://metacpan.org/module/Smart::Comments
- MattSayar 14y agoThat's a technique Steve McConnell calls "The Pseudocode Programming Process," and while it's verbose, it's not a Bad Thing. I don't do it, but I'd rather have comments like you posted than none at all.
- gnaritas 14y agoActually many of us do find it a bad thing. Useless comments are worse than no comments.
- MattSayar 14y agosed 's/\/\/.*//g' shittyComments.c
- reddit_clone 14y agoThat is legit. I have done it on occasion. It is like a relaxed form of literate programming. I don't understand this vitriol against all forms of code commenting. (I personally hate the useless, mostly empty function headers forced by some coding standard)
- einhverfr 14y agoThe problem has to do with maintaining large, complex, and frequently changing projects. If your code tells me what the program is doing the first thing I have to do when debugging is ignore the comments. If the comments describe the code this means I have to ignore all comments including those which may be relevant to my debugging. This causes a few specific problems in a collaborative environment. The first is that the comments get stale/out-of-date/etc, more quickly and are therefore consigned to the archaeology of the program rather than of current relevance. At least with spurious logging, I can take it as a sign that someone had trouble with the code here. With comments I cant even tell if it was done in pseudocode and then translated below. It is useless. The second is that you can't just add relevant comments into the mess without deleting all the other comments first. Otherwise they can't be sorted out easily or efficiently. In other words, it is worse than useless because it keeps proper, useful comments from being seen or read. Third, if there are relevant comments there, such as # This is the maximum value the standard allows for. Then I won't see these and I am more likely to miss them and hence screw something up by accident. A better approach is to recognize two things: 1) The code itself needs to be so clear, that you never need any comments for debugging (interface documentation is something very different), and 2) The code plus the documentation together has to be easily readable to the programmer. It also needs to be clear, concise, and avoid duplicating messages any more than needed. Duplication with the documentation of course is required by definition. I hear a lot of people say they have code they would like to release open source but don't want anyone to see how horrible the code is. The answer is to learn to write code with a dual audience --- human and computer --- in mind. The code comments then function like footnotes would in a text, or as a way for two or three programmers to discuss/debate differences in approach. However, they are not debugging aids.