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

“My Code is Self-Documenting”

ericholscher.com

Post reply on HN
Print view View original

71–80 of 100 posts

Re: “My Code is Self-Documenting”

#71

Post by RangerScience »

kyberias wrote: post #21
RangerScience wrote: post #16

+1 exactly this. Aside from "why", or explaining overly clever one-liners, the kind of comments I always find necessary are those providing before/after example of data during a transformation; and example strings w/ resulting capture groups for regular expressions. Example: # "tag1,tag2,tag3:val" => tags: [tag1, tag2], metadata: [tag3:val] # fun one-liner goes here

No. Those are test cases that you put in your unit tests. You don't put data examples as comments in your code.

No. Why make myself or another developer find an entirely separate file in order to comprehend a line (or three) of code? Why leave in a line of code that is all but incomprehensible without an example or explanation? Why provide a paragraph of explanation when a single line of example data will be more informative? Why further decouple the "documentation" from the code itself?

Yes, you want test cases, and that's where you also put all the weird edge case conditionals; but, it's not like you're going to copy the actual line(s) of code into the test case, so you'd either need to temporarily copy the code (or the data samples) to be adjacent, or open side-by-side editor panes, or what have... All of this is more complicated than an example.

But what about sample data that doesn't fit on one line? Then either your sample data is too complex, or this method is unsuited to your situation.

There are guidelines for maximally legible code. There are no rules. If you follow rules, someday, you will encounter a situation where the rules force you to produce sub-optimal work. "Simply" strive to write legible code, and you will succeed. Strive to follow rules, and you will succeed at following the rules; and maybe you'll succeed at writing legible code.

Re: “My Code is Self-Documenting”

#72

Post by derefr »

fooey wrote: post #28
derefr wrote: post #13

> Explaining previous approaches that didn’t work; explaining trade offs in the current implementation; marking possible improvements (TODOs) in the code; anything else you’d like to communicate with someone reading or developing the code To me, those are the functions of commit messages , not code comments. Of course, a "proper" IDE (and I don't know of any) would give you the context of the commit messages "impingi…

if you're looking at commit messages to figure out a piece of code, you're probably having a very bad day

I feel like the most consideration that is ever spent reading a particular line of code, happens during the code review for the PR that introduces that code. When you're doing a code review, you read new code at the same time that you read the commit messages. The commit messages should explain+justify the code they commit. Heck, half the reason you can break commits down into little semantic pieces with tools like `git add -p` is so you can explain/justify each piece separately.

Really, rather than what I said above, it might be better if ever line of code were just always put in context of the PR+code review that allowed it to enter the codebase. Instead of git-blame(1), github-blame(1).

Re: “My Code is Self-Documenting”

#74

Post by DrScump »

justin_oaks wrote: post #4

The biggest problem I have with comments is that they quickly fall out of sync with the code. The code gets updated but the comments stay the same. Now you have a situation worse than no comments: misleading comments. It sometimes happens with self-documenting code too, but only when someone refactors enough of the code so that the class or method no longer matches the original name.

  The code gets updated but the comments stay the same.
It's especially sad when such practices survive code review. Reviewers, that's a symptom you aren't really reviewing what's going on.

Re: “My Code is Self-Documenting”

#75

Post by DrScump »

fooey wrote: post #28
derefr wrote: post #13

> Explaining previous approaches that didn’t work; explaining trade offs in the current implementation; marking possible improvements (TODOs) in the code; anything else you’d like to communicate with someone reading or developing the code To me, those are the functions of commit messages , not code comments. Of course, a "proper" IDE (and I don't know of any) would give you the context of the commit messages "impingi…

if you're looking at commit messages to figure out a piece of code, you're probably having a very bad day

There's a difference between figuring out the how and fully understanding the why. Comments are for the latter.

Re: “My Code is Self-Documenting”

#76

Post by wellpast »

quicklyfrozen wrote: post #40
wellpast wrote: post #3

> Code comments document the why, not the how. I disagree. The _what_ is what your comments should tell me. The contract, and its preconditions and postconditions. Nothing more, nothing less.

So where would you document the "why" then? This is often the question I find most difficult to answer when reviewing code (including my own) -- after all, I can ferret out the what from the code.

If you're able to ferret out the what from the code, then your code must be defect-free.

Otherwise we need to know via the comment (contract) what is the what, so that we can fix the bug (or even know that there is a bug).

Re: “My Code is Self-Documenting”

#79

Post by emodendroket »

x0x0 wrote: post #70
sparky_z wrote: post #27

Earlier quoted context omitted.

The thing is, if somebody forgets to update a unit test, it immediately becomes obvious. If somebody forgets to update a comment, it's very easy for no-one to notice until it's much too late. There's no way to automate that check. In terms of developer resources, the act of doing updating the comments is cheap, but the act of making sure it gets done (in a systematic way) is comparatively expensive.

So add comments to your code review process. This really isn't hard. For example: python functions shall have a docstring unless trivial. For external api functions on a class, there must be at least one example. etc etc. Plus, this makes working in ipython really nice!

I usually apply something like this except only for public methods; I figure if you're digging around the private methods you probably need to look closely anyways.

Re: “My Code is Self-Documenting”

#80

Post by emodendroket »

BigJeffeRonaldo wrote: post #22
joekrill wrote: post #10

Earlier quoted context omitted.

Well this seems like a problem with code reviews (or lack of), rather than with the comments themselves.

It's a matter of incentives. Business folks don't care about comments unless they have a dev background. Your options are then to focus on the incentives present in the situation, or materially harm your own life and well-being by working extra hours to make up for your management's inability to manage.

They don't care about comments, per se, but they probably care about whether someone else can easily work on the code. I'd think (hope) most technical managers are going to encourage some sort of team review of the code and not get all the way into the weeds about what specific issues in the code review need attention.
Post reply on HN