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

51–60 of 120 posts

Re: Code only says what it does

#51

Post by gimboland »

mjw1007 wrote: post #9
macintux wrote: post #2

I’ve had similar arguments here once or twice. There’s so much context that isn’t deducible from code. You rarely need to document the “how” (that much should be evident if the code is well-written) but you absolutely should document the “why” (or, often as important, the “why not”: what code could be here but isn’t).

I agree that you shouldn't document "how", but when I'm reading unfamiliar code, I find I what I miss is "what", not "why". To my mind, in well-written code each function should be documenting its contract: what it assumes, what it guarantees if that assumption holds. (And if it turns out that what you'd write is just the function's name and its parameter and return types with a few grammatical particles added, maybe…

Yes. Floyd-Hoare logic is worth learning about in this sense — a formal system for imperative languages where the rules essentially say "given preconditions X and code Y, if X is true before you run Y, we guarantee Z to be true afterwards". I've never ever ever proven code correct using this formalism, but that way of thinking permeates my every action as a programmer.

Re: Code only says what it does

#52

Post by aflag »

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…

Which tool do you use to view commit messages and revisions for each file? I think one of the reasons this is uncommon is due to lack of tooling (or wide-spread knowledge of them). I'd really like to be able to easily see all the previous commits that affected a specific line while I'm editing code. But I usually have to resort to interacting with git, rather than having something popping up on my screen (I use pycharm and vim regularly).

Re: Code only says what it does

#53

Post by DreadY2K »

henryfjordan wrote: post #17
baddox wrote: post #16

Earlier quoted context omitted.

It seems to be fairly common for experienced programmers to point to unit test code as a way to explore or understand an open source software project. I don't doubt that this works for them, but it definitely doesn't work for me. When I'm trying to explore a new software project, the first thing I want to do is find the relevant "entry point," which is arguably the exact opposite end from the unit test code.

Tests that target the surfaces of the project (public APIs, endpoints, etc) and code examples start to blend together at some point. "Here's a basic example that should do X" sounds a lot like "Do something basic and assert it does X".

One thing that I like about Rust is that they actually allow you to merge those two into one. In your documentation of anything, you can include code snippets, and those code snippets become tests that can ensure that the documented behavior still applies to the current code.

Re: Code only says what it does

#54

Post by tigershark »

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.

Clear code and clear tests absolutely don’t need comments that explain them if they are really clear, at least for me. Comments are extremely useful to explain something unexpected. Commit messages are too limited to explain properly a use case, but linking to a Jira with the proper explanation does the trick. From the tests you can see both the typical use cases and the correct way of using some piece of code and have a guarantee that the code respects the specification. With the comments you have none of this guarantees. I had the opposite experience from you apparently, the people that I worked with that used excessive comments were not up to par with the rest of the team. Also it may related to the mental model, comments just break my flow and make more difficult for me to read the code.

Re: Code only says what it does

#55

Post by ativzzz »

corbins wrote: post #18

The counterexample here is the declarative style of programming. Most ideally this looks like an executable spec and is documentation itself.

Sure, but then you offload the complexity to the functions used as the declarative building blocks, so you do the documenting in a different place, though you will probably end up documenting complex declarative business logic anyway. (like why is process X that is so similar to process Y require Z different declarative blocks)

Re: Code only says what it does

#56

Post by kevinschumacher »

aflag wrote: post #52
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…

Which tool do you use to view commit messages and revisions for each file? I think one of the reasons this is uncommon is due to lack of tooling (or wide-spread knowledge of them). I'd really like to be able to easily see all the previous commits that affected a specific line while I'm editing code. But I usually have to resort to interacting with git, rather than having something popping up on my screen (I use pycha…

Not the person you were replying to, but in PyCharm:

- right click on the line number, click Annotate; this gives you the commit date and author in the gutter

- hover over the date/author name; this gives you the commit hash and message

- click on the hash itself in the popover; this shows the git commit graph on the Version Control tab

- right click on the date/author name, click Annotate Revision; this opens up the version committed then, with its git blame in the gutter.

Re: Code only says what it does

#57

Post by nfRfqX5n »

aflag wrote: post #52
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…

Which tool do you use to view commit messages and revisions for each file? I think one of the reasons this is uncommon is due to lack of tooling (or wide-spread knowledge of them). I'd really like to be able to easily see all the previous commits that affected a specific line while I'm editing code. But I usually have to resort to interacting with git, rather than having something popping up on my screen (I use pycha…

I use gitlens for vscode

Re: Code only says what it does

#58

Post by ponker »

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've had that experience describing the plot of a novel to friends of mine. The novel is pretty complex and covers ideas in crime, internet anonymity, memetics/virality, and then some technical things with vehicles and atmospheric science. Some friends I've talked it through with, they come up with ideas to add stuff and it's like "that makes no sense for this novel, but it's not a dumb idea given how little of the theory of the novel I've communicated to you." Whereas other friends seem to immediately grasp onto the theory and make suggestions that actually fit with the overall concept very well, and usually recommend small changes rather than wholesale plot rearchitectures. It's like an architect coming in and saying "we should move this door two inches so that this door doesn't bang this wall" vs. "We should build this whole house as one story into the side of a cliff."

Re: Code only says what it does

#59

Post by aequitas »

My pathway into software development was through electrical engineering and embedded systems. So I don't know if this applies to other ways into software development as well. But what really stood out to me in the beginning was how useless code comment where. I would almost always see code like this:

  x = 1;      // assign 1 to x
  y = x * 2;  // multiply x by 2
I don't know if it was because they thought electrical engineers needed to be explained everything about code. Or if it was because all teaching material used this style and people just copied it. But I never understood why you would add comments like this, but had to do so anyways otherwise I would not pass my exams.

It took me a while to learn that comments are the tool in which you can express your expectation of what the code should do.

Re: Code only says what it does

#60

Post by wanderr »

phendrenad2 wrote: post #45

It gives me no end to pain that "Comments are lies because they aren't code" is a fad that we're currently suffering through as an industry. For decades prevailing wisdom was that comments were a net benefit, and now in the last few years this trend has become prevalent. How much perfectly-good code is going to have to be rewritten from scratch in 10 years because no one remembers what it does?

If no one understands what it does, it's not perfectly good code is it? Of course there are rare cases where code cannot be simplified, made more readable or self explanatory and in those cases comments are vital. But the aim should be for the vast majority of code to be easily readable by humans.
Post reply on HN