Or to put it more succinctly: Code is the what, comments are the why/why not.
On Comments in Code
201–210 of 238 posts
Re: On Comments in Code
#202Earlier quoted context omitted.
If your method documentation is out of date, the problem is not about the doc. The problem is that someone on your team drastically changes existing methods behavior instead of writing new ones, and by doing that, is changing the behavior every historical caller expected. I really think that if your changes are so important that they need the doc to be updated, it’s probably that you should write a brand new method.…
It is not about my team. It is about people. In the world where team members last ~2 years and move on, expecting that documentation is left not updated is in my opinion perfectly valid assumption.
I was not directing my comment to your coworkers. I was just arguing that a documentation can only be out of sync if the method's intention is changed. And if an existing method intention is changed, your problem is not the out of sync documentation, but the fact you probably broke something in your existing code, not in the years to come, but today.
Re: On Comments in Code
#203Earlier quoted context omitted.
// // Dear maintainer: // // Once you are done trying to 'optimize' this routine, // and have realized what a terrible mistake that was, // please increment the following counter as a warning // to the next guy: // // total_hours_wasted_here = 42 //
The inverse of this is also useful: // Dear maintainer, // The code which follows was hacked together under desperate pressure. // It's not smart. // It's not doing anything really subtle. // It's the only thing we could get to work in the time. // If you want to chuck it and replace it, you absolutely should.
It's useful, until you realize you have this on 90% of your code.
Re: On Comments in Code
#204The author touches on this a bit but I want to state this really simply: Codes needs "why" comments, not "what" comments. The "what" can be done by self-documenting code, _most_ of the time. You still need to write "what" comments sometimes, don't rule it out completely. And you routinely need to write "why" comments, self-documenting code will never provide the context of "why". Write more "why" comments.
> _most_ of the time This is the thing that annoys me with arguments about all this. I will generally say "document the 'why' and not the 'what'; if the 'what' isn't clear from the code, fix the code to make it clear". And people will say "that's invalid because sometimes you really do need to do something clever and the 'what' needs to be documented" or whatever. And yes, that's fine! Stop taking everything people s…
> And people will say "that's invalid because sometimes you really do need to do something clever and the 'what' needs to be documented" or whatever.
Yep, that'll happen, and when it does, you document why you documented the 'what'! :P
This kind of lazy black-and-white thinking is what 'consistency is the hobgoblin of small minds' is talking about. The exception proves the rule (...most of the time...)
Re: On Comments in Code
#205Earlier quoted context omitted.
> _most_ of the time This is the thing that annoys me with arguments about all this. I will generally say "document the 'why' and not the 'what'; if the 'what' isn't clear from the code, fix the code to make it clear". And people will say "that's invalid because sometimes you really do need to do something clever and the 'what' needs to be documented" or whatever. And yes, that's fine! Stop taking everything people s…
I think people often lean too far in favour of "self-documenting code," and "what" comments wind up being underused. The idea of self-documenting code is that the documentation is encoded in the function and variable names, more or less. Sure, extraneous comments should usually be avoided, but frankly, sometimes a couple sentences of plain English is just clearer. I'd rather people just tell me what's going on than t…
It's much easier to fool yourself into thinking you're writing "self-documenting code" if your "documentation" is just a natural language rephrasing of your code.
Re: On Comments in Code
#206The author touches on this a bit but I want to state this really simply: Codes needs "why" comments, not "what" comments. The "what" can be done by self-documenting code, _most_ of the time. You still need to write "what" comments sometimes, don't rule it out completely. And you routinely need to write "why" comments, self-documenting code will never provide the context of "why". Write more "why" comments.
Should my 'why' comment go further than a Jira number?
That depends on whether or not you think the Jira ticket will outlast your code or not. If the company will definitely never replace Jira then no. If there is a chance that they will, and for your sake I really hope there is, then you'll need a better comment.
Re: On Comments in Code
#207Earlier quoted context omitted.
When your coding standard enforces 80 characters, you end with a single logical statement split across many lines. This quickly approaches un-readability if you fetishize self documenting code. In my opinion, short variable and function names with a comments are often more readable that self documenting behemoths, e.g., double compute_angular_acceleration_in_radians_per_second_per_second(double torque_in_newtons_per_…
What about the day the Mars climate orbiter was lost because one piece of code wrongly assumed that the units of figures out of the other piece of code? :) I find that you do sometimes need symbol names that long even though it's a code smell indicating something else is up - usually scopes that are too large or insufficiently expressive types. I view excessively long variable names as a midpoint on a journey to impr…
While what you say about long variable names can be right in certain circumstances, the example with the wrong units is inappropriate.
In my opinion any code that deals with physical quantities, but which does not use dedicated types for each kind of physical quantity, where the type definitions include the units used, is erroneous.
Any mistake like in the Mars orbiter must be detected at compile time.
Re: On Comments in Code
#208Earlier quoted context omitted.
Some people advocate putting lots of stuff into commit messages, which makes me think I'm missing something -- commit messages are much less visible/accessible than comments in my workflow, so I don't expect my commit message to be seen. Do you always read the whole git history of a file before editing it? What interface do you use for that?
It’s a dumb idea, because that content gets lost as soon as you move things around.
Counter-point: moving things around in a way which doesn't preserve history is a dumb idea.
Moving/renaming a file? Commit the deletion and insertion together, preferably with no other changes (including to the contents of the file; commit those afterwards). In the best case, VC will treat this as a move and showing the history will include that of the old place/name. In the worst case, that history of file 'foo' will "end" with a commit like 'Rename bar to foo', with a diff showing the content moving from 'bar' to 'foo'; we can continue reading the history by switching to 'bar' if we want.
Moving code from one file to another? Similar story: commit the insertion and removal together; preferably with little/nothing else in that commit; preferably with a commit message explaining the change. This way, the code doesn't appear from nowhere in the commit history: when we look at the commit where it appears, we will also see where it came from before.
Moving a file from one repo to another? Dump that file's history as a patch, apply that patch in the new repo, then clean up (e.g. rename, move, etc. as appropriate). Alternatively, for larger sets of changes, add the old repo as a remote for the new repo, make a branch in the old repo which contains only those parts we want to move, fetch that branch into the new repo and merge it, then remove the remote.
Re: On Comments in Code
#209Earlier quoted context omitted.
// // Dear maintainer: // // Once you are done trying to 'optimize' this routine, // and have realized what a terrible mistake that was, // please increment the following counter as a warning // to the next guy: // // total_hours_wasted_here = 42 //
The inverse of this is also useful: // Dear maintainer, // The code which follows was hacked together under desperate pressure. // It's not smart. // It's not doing anything really subtle. // It's the only thing we could get to work in the time. // If you want to chuck it and replace it, you absolutely should.
Hey, that one I actually can replace with self-documenting code! Oh joy!