Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Code only says what it does

brooker.co.za

Post reply on HN
Print view View original

91–100 of 120 posts

Re: Code only says what it does

#91

Post by namelosw »

ris wrote: post #24

So many times this. "Clear code shouldn't need comments" - clear code can make it easy to see what but it can never say why . Let me know what corner cases you thought about when you wrote this. "The comments are in the commit messages" - almost nobody ever goes looking for them there, they're effectively invisible from `git blame` when they remove lines, people rarely make fine grained enough commits to be able to t…

> Let me know what corner cases you thought about when you wrote this.

We actually rarely use comments in code. The best way to reflect the corner cases are tests. It is the comments codified.

> but it can never say why

Usually people don't need to know why on small piece of code unless it's a high-level stuff. For high-level stuff we have architecture decision records (ADR) which records the motivations and situations. But we also keep it very short or people would never read those.

> "Nobody ever updates comments, so they're always out of date" - don't hire such people.

That's a really high standards. It's almost like "We have bugs", "Well, then don't hire people writing bugs"...

There are many ways of breaking comments. For example, someone changed module A, then the properties on module B changed because of A. If it's a test it will reflects on CI, but if it's a comment there's almost no way for people to realize that.

Re: Code only says what it does

#92

Post by sanderjd »

phendrenad2 wrote: post #39
sanderjd wrote: post #28

Earlier quoted context omitted.

> almost nobody ever goes looking for them there I've seen this claim a number of times and it's always so odd to me. One of my most common activities each day - certainly more common than the activity of writing new code - is reading the commit history for different files. It's always surprising to me to hear that this is an uncommon thing to do. Edit to add: But I also think comments and documentation of all kinds…

Commit messages are much harder to get to for a given line of code than a comment would be.

I actually find file and directory level history useful more often than the line-level annotate/blame history that seems to get all the attention. I do find line level history useful as well, I'm just saying less often.

At the directory level, I look at the history of commit messages to get a sense for how the module(s) under that directory have evolved over time. At the file level, I look at the history of commit messages and often dig into the associated diff in order to see how the API and/or implementation have evolved. I'll often follow the file-level diff to the full commit to see what the entire change entailed. This gives me tons of context on the what and the why of a codebase's evolution, and it's all aided by good commit messages.

Line level blame/annotate is sometimes useful when I'm trying to trace how some particular implementation came to be, but it is easy to lose the thread across deletions and renames, which I find file and directory level history to be much more resilient to.

Re: Code only says what it does

#93

Post by gkfasdfasdf »

ris wrote: post #24

So many times this. "Clear code shouldn't need comments" - clear code can make it easy to see what but it can never say why . Let me know what corner cases you thought about when you wrote this. "The comments are in the commit messages" - almost nobody ever goes looking for them there, they're effectively invisible from `git blame` when they remove lines, people rarely make fine grained enough commits to be able to t…

I've found that questions during a code review make excellent fodder for comments. I.e. if someone has a question (not necessarily an issue) about a piece of code, it's a good bet someone might have a similar question when reading the code later.

Re: Code only says what it does

#95

Post by [deleted] »

hinkley wrote: post #69
dkarl wrote: post #33

This is a major problem with code: You don't know which quirks are load-bearing. You may remember, or be able to guess, or be able to puzzle it out from first principles, or not care, but all of those things are slow and error-prone. This is a problem from both the negative (not breaking things) and positive (knowing how to add things) perspectives. The positive perspective was written about by Peter Naur in one of m…

I think I have to disagree with Naur on this, in that people using the Scientific Method don't ship their theories, but we do. As a scientist who has just succeeded in testing a hypothesis, I now need to go back and document a simplified series of steps that should lead any independent party to the same phenomenon. Once we are on the same page, they can confirm or refute my theory based on their own perspectives on t…

[deleted]

Re: Code only says what it does

#96

Post by rpdillon »

shepherdjerred wrote: post #90
phendrenad2 wrote: post #39

Earlier quoted context omitted.

Commit messages are much harder to get to for a given line of code than a comment would be.

Not if you use a nice IDE: https://www.jetbrains.com/help/idea/investigate-changes.html...

Or even just Emacs. http://www.gnu.org/software/emacs/manual/html_node/emacs/Old...

Re: Code only says what it does

#97

Post by Twisol »

perl4ever wrote: post #86
thdrdt wrote: post #63

Earlier quoted context omitted.

The only time I place comments is exactly this: to explain why. Today I just had this example. I placed a little sleep in a loop. But there is absolutely no way to know why it is there. So I inserted a comment to explain the loop is DOSing a server by constantly requesting it and the sleep will reduce the load on that server. Those comments are not only for others but also for yourself. Even weeks from now it is easy…

Yeah, but the phrase "only time" somewhat suggests you use "why" as an excuse to comment rarely. You can nonetheless write such a comment for essentially every line. My job description is not "developer" at the moment, so when I was asked to comment my code in order to turn it over to the developers, I looked for some standards. The document I found said, more or less, that you should write comments such that if the…

> you should write comments such that if the code was removed, someone could use the comments to completely reconstruct it.

I understand that this is just a rule of thumb, but it's so far from anything I could expect to happen in reality that it serves as no justification at all. A codebase is a living entity that grows and changes over time. Without sound justification that butresses both when and when not to comment, advice like this can lead to exactly the brittle comments that disillusion people from commenting as a whole.

Comments are just a part of a healthy breakfast. You want the code to be as clear as possible, both in the small (algorithmically) and in the large (architecturally). When the code must necessarily fall short, comments must fill that gap -- and only that gap. (Other forms of documentation serve other needs.)

It's like unit tests and integration tests: you want as many unit tests as possible, to give you assurance that the pieces from which you assemble your system are correct. Where unit tests cannot speak, other kinds of tests fill the gaps. But if you try to build your test suite out of integration tests, you'll end up pretty miserable.

Re: Code only says what it does

#98

Post by otterley »

ChrisSD wrote: post #7

A big issue with documenting what the code does is that the code and documentation can very quickly fall out of sync. As this posts says, it's much more useful to document the intent of the code, or why there's this mess of seemingly hacky code (see issues #80681, #82108, #66065). Also be wary of unit tests that are overly tied to the specifics of an implementation. These can be worse than useless when it comes to ch…

A good way of avoiding this trap is to require updated comments as a condition of merging a pull request.

Re: Code only says what it does

#99

Post by perl4ever »

Twisol wrote: post #97
perl4ever wrote: post #86

Earlier quoted context omitted.

Yeah, but the phrase "only time" somewhat suggests you use "why" as an excuse to comment rarely. You can nonetheless write such a comment for essentially every line. My job description is not "developer" at the moment, so when I was asked to comment my code in order to turn it over to the developers, I looked for some standards. The document I found said, more or less, that you should write comments such that if the…

> you should write comments such that if the code was removed, someone could use the comments to completely reconstruct it. I understand that this is just a rule of thumb, but it's so far from anything I could expect to happen in reality that it serves as no justification at all. A codebase is a living entity that grows and changes over time. Without sound justification that butresses both when and when not to commen…

> advice like this can lead to exactly the brittle comments that disillusion people from commenting as a whole

As I turn this over in my head, it doesn't sound that convincing because the whole "code should be self-explanatory" ethos seems to me just as susceptible to encouraging bad behavior. Saying something is clear allows you to elevate yourself and blame others if they don't follow. Expecting people to judge their own communication is a definite conflict of interest. Exaggerated commenting requirements as I described are at least a reminder that you should try to err on the other side.

Also, for context, the agency I work for is responsible for an accounting system that affects a lot of people and is very much not a "move fast and break things" place. The most exciting thing that happens year after year is reducing the scheduled downtime window(s). Even that obviously must have diminishing returns.

The other thing is that in my particular case, the code I wrote is not directly applicable to the accounting system and is written in a different language, so anyone trying to modify it will probably be relatively inexperienced and there is zero chance of anyone being hired to work on it.

Re: Code only says what it does

#100

Post by nardi »

False. If we used only meaningless symbols like “A”, “B”, etc. for names, then it would be true. But if I have a method named “addItemToCart”, then I know what it ought to do. If it does NOT in fact add the item to the cart, then I’ve found a bug. It’s true that a short method name might not capture all of the subtleties, but usually the variable names within the method can give you an idea of what the intent of the programmer is as well. Obviously there are still things you should write comments for, but really well-thought-out names can get you surprisingly far.
Post reply on HN