Code only says what it does • Hacker News Board

Re: Code only says what it does

#31

Post by Braxton_Hicks » Mon, Jul 06, 2020, 7:14 PM UTC

sanderjd wrote: post #28

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…

> 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…

Agreed. I think the "nobody ever goes looking for them" case is common for code bases where people are not writing good useful commit messages.

Re: Code only says what it does

#32

Post by foodigger » Mon, Jul 06, 2020, 7:19 PM UTC

most people cant read it anyway so what does it matter?

Re: Code only says what it does

#33

Post by dkarl » Mon, Jul 06, 2020, 7:19 PM UTC

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 my favorite software engineering papers, "Programming as Theory Building," in which he describes how the original authors of a codebase have a mental model for how it can be extended in simple ways to meet predictable future changes, which he calls their "theory" of the program, and how subsequent programmers inheriting the codebase can fail to understand the theory and end up making extensive, invasive modifications to the codebase to accomplish tasks that the original authors would have accomplished much more simply.

I highly recommend finding Naur's paper (easily done via Google) and reading it to understand why divining the "theory" of a codebase is a fundamentally difficult intellectual problem which cannot be addressed merely by good design, and not with 100% reliability by good documentation, either.

Re: Code only says what it does

#34

Post by cjfd » Mon, Jul 06, 2020, 7:22 PM UTC

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…

Clear code needs some comments. Not many, though. If you write a numerical algorithm it probably needs an explanation or a reference to where it came from or something like that. Generally, one needs a comment when it is difficult to figure out why something was written that way. In many cases comments are not needed. I perhaps write a comment once every ten files or maybe even less but then it tends to be a rather long comment because the thing explained is very non-obvious. The kind of comment that I hate seeing is when somebody feels the need to tell me what methods are constructors or similar such nonsense.

Re: Code only says what it does

#35

Post by phlakaton » Mon, Jul 06, 2020, 7:29 PM UTC

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…

> people rarely make fine grained enough commits to be able to target specific lines or blocks

Take your own advice then: don't hire such people. Why would you insist on maintaining documentation and not maintaining a reasonable change log in your commits, if knowing "why" is important to you?

(I make the advice tongue-in-cheek btw. Better to educate and lift developers up wherever you can than just freeze them out. Not everyone has the experience with these things that we do.)

There's not a one-size-fits-all solution here. Different orgs handle their code history different ways, but having tasted the power Git gives you over certain other VCSes to make the commit log really useful as a record of change, and having taken advantage of that feature several times myself, I wouldn't want to go back.

This follows another comment I just made on the topic: https://news.ycombinator.com/item?id=23743973

Re: Code only says what it does

#36

Post by selykg » Mon, Jul 06, 2020, 7:37 PM UTC

trixie_ wrote: post #13

If I had a nickel for every programmer who thought their code was so good it didn't require comments... or thinks somehow that unit tests make up for comments... only to come back years later and have no idea why the logic is working how it is.

This was a thing at my last job. The lack of comments always made me cringe. While not every line needs a comment, there's a reason why comments would be useful, especially in security software.

I learned a lot of bad habits there and I'm glad I no longer work there.

Their excuses were literally "no one reads comments" "no one keeps comments up to date" "my code is self documenting" etc.

Re: Code only says what it does

#37

Post by codegladiator » Mon, Jul 06, 2020, 7:38 PM UTC

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…

> "Clear code shouldn't need comments"

That's like saying articles don't need summary.

Re: Code only says what it does

#38

Post by mjb » Mon, Jul 06, 2020, 7:44 PM UTC

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…

Thanks for sharing that, I'll read it!

I do agree that comments, documentation, and other artifacts aren't sufficient to solve this problem. The closest I've come is with formal specification, where the intent of the program can be communicated very clearly. Multiple approaches are needed. One of those approaches is continuity: Keeping people around who are familiar with the code base and can pass on this knowledge to others.

Re: Code only says what it does

#39

Post by phendrenad2 » Mon, Jul 06, 2020, 7:44 PM UTC

sanderjd wrote: post #28

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…

> 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.

Re: Code only says what it does

#40

Post by [deleted] » Mon, Jul 06, 2020, 7:45 PM UTC

trixie_ wrote: post #13

If I had a nickel for every programmer who thought their code was so good it didn't require comments... or thinks somehow that unit tests make up for comments... only to come back years later and have no idea why the logic is working how it is.

[deleted]