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

91–100 of 100 posts

Re: “My Code is Self-Documenting”

#91

Post by js8 »

derefr wrote: post #17
js8 wrote: post #12

Earlier quoted context omitted.

As others have said.. Code doesn't depend on variable/function names either. Yet you don't argue they fall out of sync, you simply update them. And this should be done for comments, too.

Code does depend on variable/function names. When you change the name at the definition, your code fails to compile until you also change the name at each usage. This is not true of comments. If we could make outdated comments produce compilation errors, we would live in a wonderful world :)

What I was saying that choice of identifier of the variables/function does not matter for the functionality, as long as they all refer consistently to the same thing. Take code obfuscated by replacing variable names, for instance. People don't argue we should run the code through such obfuscator out of worry that the identifiers can change meaning through code changes.

> If we could make outdated comments produce compilation errors, we would live in a wonderful world

It is impossible. The whole point of having comments (and also identifiers) is to tie the code to things that are not formally described. If we would formally describe them, they would become the code.

You could, at best, mark identifiers in comments (and what their refer to), and then you could use this to hint at comments that need to be updated (as somebody else mentioned). But it will never be a perfect process, because there will always be a boundary between formal and informal.

Re: “My Code is Self-Documenting”

#92

Post by BigJeffeRonaldo »

vinceguidry wrote: post #54
BigJeffeRonaldo wrote: post #48

Earlier quoted context omitted.

But it does. It depends on the organization, but there are groups where chugging coffee, talking a lot, and pumping out dozens of half-working features by coding like a drunk cowboy will get you promoted and recognized as a team player, while pushing back to take time and do things right will have you reprimanded. Many such cases out there.

My point is that you shouldn't push back. Just do things the way they need to be done, and it takes as long as it takes. A manager looks at a programmer bringing up something like unit testing as "why the fuck is he asking me about this, it's his job? Obviously because he's asking me it's outside of his professional ken, so that means it's going to take absolutely forever." Out loud he'll just say, "Can you just get…

This generally won't work for straight forward game theoretic reasons. Boss thinks you're slow->boss brings on h1b consultant willing to pump out spaghetti code and toady up to him->you looking for a new job. Organizations get what they ask for

Re: “My Code is Self-Documenting”

#93

Post by eveningcoffee »

derefr wrote: post #17
js8 wrote: post #12

Earlier quoted context omitted.

As others have said.. Code doesn't depend on variable/function names either. Yet you don't argue they fall out of sync, you simply update them. And this should be done for comments, too.

Code does depend on variable/function names. When you change the name at the definition, your code fails to compile until you also change the name at each usage. This is not true of comments. If we could make outdated comments produce compilation errors, we would live in a wonderful world :)

Counter example: method findSomethingByParam1(param1) was changed to findSomethingByParam1(param1, param2). Seeing such method name in the call stack can be highly misleading.

Re: “My Code is Self-Documenting”

#94

Post by vinceguidry »

BigJeffeRonaldo wrote: post #92
vinceguidry wrote: post #54

Earlier quoted context omitted.

My point is that you shouldn't push back. Just do things the way they need to be done, and it takes as long as it takes. A manager looks at a programmer bringing up something like unit testing as "why the fuck is he asking me about this, it's his job? Obviously because he's asking me it's outside of his professional ken, so that means it's going to take absolutely forever." Out loud he'll just say, "Can you just get…

This generally won't work for straight forward game theoretic reasons. Boss thinks you're slow->boss brings on h1b consultant willing to pump out spaghetti code and toady up to him->you looking for a new job. Organizations get what they ask for

The boss doesn't have to think you're slow. You could... gasp... be good at your job.

Re: “My Code is Self-Documenting”

#95

Post by edblarney »

emeraldd wrote: post #30

This is an odd one for me, 90% of the time I wind up subconsciously ignoring comments that exist in code. It's almost as if I can't see them on the screen. I've been in at least one argument with a coworker where I realized I was ignoring the existence of the comment he was referencing a line above the code we were looking at. On the other side of that, I'm usually adding comments about what's going on all over the p…

"90% of the time I wind up subconsciously ignoring comments that exist in code."

That's ok - because they are there for reference purposes.

So you can ignore them most of the time.

When there's an issue, or you are reading unfamiliar code - you can reference them.

I leave notes in the code as to the oddities/undocumented nature of weird API dependencies, and of things that were tried in the past and failed.

So many times I've tried to compile some off-the-shelf thing and failed because I didn't read the release notes.

You just have to read the release notes :)

So when you're perusing an unfamiliar module, read the comments :)

I grasp that they can become stale, but on the whole, decent comments are better than none.

Re: “My Code is Self-Documenting”

#96

Post by gnaritas »

codr4life wrote: post #63
gnaritas wrote: post #31

Earlier quoted context omitted.

If your comments just say what the code does, they're redundant and unnecessary. Good comments explain things the code can't, like why you chose a particular algo, or why some piece of code needs to exist. Most code when written well requires no comments. Comments like yours, that repeat what the code does, I simply delete.

Like I said, I don't agree with that particular broken record; there is value in stating the intent of code in normal prose as documentation.

Yes there is value, comments like those let me know which developers need more training to learn how to code cleaner.

I know what you said, and I disagreed; responding back by repeating your disagreement doesn't add any value to the conversation.

Re: “My Code is Self-Documenting”

#97

Post by edblarney »

kyberias wrote: post #20

I think the Uncle Bob quote is good: "Code comments are not the Schindler's List. They're not pure good." If a line of code has a comment attached to it, the reader needs to understand both the code and the comment. The comment is written in natural language. There are multiple ways of understanding it. It must be written with great care so that people reading it don't misunderstand it. Otherwise it will likely just…

"The reader must read and understand it in any case."

Because in the cases wherein the code is abstract or dense, a little 'English' can go a long way.

Especially when making use of APIs that are weird and have weird behaviours.

AKA: "I'm breaking xyz convention here because API abc has the following odd, undocumented behaviour (i.e. returns nulls when it should not)"

Comments are not always good, but if there is any reasonable thoughtfulness to them, they will be 'mostly good'.

Re: “My Code is Self-Documenting”

#98

Post by BigJeffeRonaldo »

vinceguidry wrote: post #94
BigJeffeRonaldo wrote: post #92

Earlier quoted context omitted.

This generally won't work for straight forward game theoretic reasons. Boss thinks you're slow->boss brings on h1b consultant willing to pump out spaghetti code and toady up to him->you looking for a new job. Organizations get what they ask for

The boss doesn't have to think you're slow. You could... gasp... be good at your job.

I can tell you're upset, Vince, so I'll be the one to end this discussion.

Re: “My Code is Self-Documenting”

#99

Post by MaulingMonkey »

joekrill wrote: post #55
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.

But it's not immediately obvious if someone changes something that isn't covered by a unit test. Or forgets to create a unit test. Does that mean we should just abandon writing unit tests altogether? You could always use a tool like Danger ( http://danger.systems/ ) to inspect your code and warn you when code has been updated, but comments nearby have not been.

> But it's not immediately obvious if someone changes something that isn't covered by a unit test. Or forgets to create a unit test.

This is what code coverage analysis/metrics try to address.

> You could always use a tool like Danger (http://danger.systems/) to inspect your code and warn you when code has been updated, but comments nearby have not been.

I'd worry about tuning out said warnings after too many false positives. Comments regular enough to not generate too many false positives can generally be turned into real syntax of some description.

Re: “My Code is Self-Documenting”

#100

Post by MaulingMonkey »

vinceguidry wrote: post #94
BigJeffeRonaldo wrote: post #92

Earlier quoted context omitted.

This generally won't work for straight forward game theoretic reasons. Boss thinks you're slow->boss brings on h1b consultant willing to pump out spaghetti code and toady up to him->you looking for a new job. Organizations get what they ask for

The boss doesn't have to think you're slow. You could... gasp... be good at your job.

Being good at your job won't magically make you fast at fixing up other people's spaghetti code. It won't let you ship 3 working features faster than someone else who's also "good" at their job ship 6 mostly broken features. It won't convince your manager that the former is actually getting more work done than the latter, and won't prevent them from thinking the first guy is slow and the second guy is fast.

But for what it's worth, I agree with you in that I'm still on the hook. Either to help educate my manager, or to pick managers who already understand this stuff.

Post reply on HN