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

101–110 of 120 posts

Re: Code only says what it does

#101

Post by Twisol »

perl4ever wrote: post #99
Twisol wrote: post #97

Earlier quoted context omitted.

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

> the whole "code should be self-explanatory" ethos seems to me just as susceptible to encouraging bad behavior.

I hope it's clear from what I wrote that I don't think code can be perfectly self-explanatory. I don't think it's all-or-nothing in either direction. I do, however, think that direct clarity is the first line of defense, followed by comments and other documentation artifacts to capture what the code cannot.

> Expecting people to judge their own communication is a definite conflict of interest.

I don't disagree: while I think it's possible to train your communications so that you meet a minimum bar by default, that training necessarily comes by testing your communication against others. We have peer review processes in part to help account for this: if something isn't clear, that's the first forum of opportunity to address it.

The (only) good thing about pithy quotes like "you should be able to rewrite it from the comments" and "code should be self-explanatory" is that they stake out concrete, extreme positions that can be judged on their merits. The space of practice is much wider than the ideologically pure boundary.

I'm sure that, for your situation, commenting everything such that it could be rewritten from scratch makes sense. If you needed to pass ownership of a codebase more or less instantaneously, it may make sense as a kind of snapshot of the intent behind the codebase at that point in time.

I also work with some critical, ancient software. I wish I had more documentation of all kinds, but mostly because it would help me decipher the codebase itself. I wish the codebase didn't need the degree of deciphering that it does. It makes even minor changes take longer just to make sure I'm not breaking something else along the way -- to say nothing of major changes, which while relatively rare do come along. Again: my biggest need is to decipher the codebase itself, and I would rather it inherently require less effort to do so. There are straightforward principles, like "avoid globals", that are violated left and right in this software by no real necessity. Commenting these aspects is a simply a band-aid on something that should have been engineered better from the beginning.

Re: Code only says what it does

#102

Post by ThomasDeutsch »

The "why" can be expressed in code.

Think of "Event Storming". A great way to talk about the "why" and to grow an understanding of how a problem can be solved. The result can be multiple "flows" that describe a series of events from the first command to the expected outcome.

We have the option to directly translate a flow to code. And by keeping the flow in one place, we also keep a direct mapping from our code to the EventStorming-results. The "why" will not be lost. The code can contain multiple flows and every flow can have a scenario-like description like: "the user is able to select a product"

This is what my passion is all about. To keep the "why" in one place. This also enables better collaboration between multiple disciplines (like UX DEV)

This is the idea behind scenario based programming. I am working on an open source project: https://github.com/ThomasDeutsch/flowcards

Write me a line if you would like to get involved.

Have you found other solutions for this problem?

Re: Code only says what it does

#103

Post by jbay808 »

RandallBrown wrote: post #83
trixie_ wrote: post #70

Earlier quoted context omitted.

Right you are exactly the kind of person I'm talking about. You think your code is clear. It is not. The logic your code performs is the distilled by-product of higher level reasoning. Reasoning that should be the basis of your comments. People reading your code will not be in the same mind state that you were in when you wrote it. That is what the comments are meant to assist with. If you write comments for anyone,…

If someone's code isn't self explanatory from the naming and organization, why would you expect their comments to do a better job? The vast majority of comments I see are completely useless, either giving incorrect/outdated information or restating exactly what the code says. I've even made comments nearly the same color as the background in my text editor so it's easier for my brain to skip them. Comments certainly…

I don't even mind if the comments restate what the code says. The code only says what it does, not what it is intended to do.

Re: Code only says what it does

#104

Post by simonh »

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…

>...or not care, but all of those things are slow and error-prone

Nah. Not caring is pretty quick and simple. It has served me well!

Seriously I do agree though. One mistake I've seen a lot is assuming that an extensive code base, developed by competent engineers, but which is very complex needs simplifying or rewriting in a simpler way.

Often that complexity is there for a reason, covering platform, customer or situation specific edge cases discovered through hard won experience and feedback from production use.

Twice I've worked at companies where a massive project to replace the core product with a new clean sheet implementation killed the business. That doesn't mean clean sheet implementations are always bad, not at all, but they can like a nice clean beautiful opportunity while actually being blood curdlingly risky.

Re: Code only says what it does

#105

Post by tigershark »

jbay808 wrote: post #103
RandallBrown wrote: post #83

Earlier quoted context omitted.

If someone's code isn't self explanatory from the naming and organization, why would you expect their comments to do a better job? The vast majority of comments I see are completely useless, either giving incorrect/outdated information or restating exactly what the code says. I've even made comments nearly the same color as the background in my text editor so it's easier for my brain to skip them. Comments certainly…

I don't even mind if the comments restate what the code says. The code only says what it does, not what it is intended to do.

The tests say what the code is supposed to do. And, unlike the comments, they cannot be out of sync with the code because they will fail.

Re: Code only says what it does

#106

Post by prerok »

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…

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

I think this is an "archaic" concept in line with heavily structured methodologies, where everything is first documented in meticulous detail and then the code will map to documentation 1:1. Anyone heard of/still remembers SSADM?

Anyway, that approach has turned out to be less than practical, to say the least, and was one of the reasons the agile methodologies were invented in the first place.

The point today is that the documentation should supplement the code to make the other developers/readers of the code aware of the hidden intricacies of the code. Lately, we are focusing on the "why" because it is turning out to be the most useful. As you say, there are still questions on the level of detail of the "why" we need to capture. Mostly, people just go with their gut feeling and that's fine, as long as we take care to calibrate the feeling through feedback and improve it with time.

Maybe there could be a formal way of knowing what needs more clarification but I doubt it. We still lack a way of mapping our human level understanding of the system to a formal machine analyzable system, so a computer analyzing our program cannot know what step in the program would be surprising to a human reader.

Re: Code only says what it does

#107

Post by titzer »

simonh wrote: post #104
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…

>...or not care, but all of those things are slow and error-prone Nah. Not caring is pretty quick and simple. It has served me well! Seriously I do agree though. One mistake I've seen a lot is assuming that an extensive code base, developed by competent engineers, but which is very complex needs simplifying or rewriting in a simpler way. Often that complexity is there for a reason, covering platform, customer or situ…

> One mistake I've seen a lot is assuming that an extensive code base, developed by competent engineers, but which is very complex needs simplifying or rewriting in a simpler way.

Omg, this yes. I've made this mistake countless times. I'e done my share of rewrites or refactorings that ended poorly. Work long enough on a big project, and junior engineers will do it to your code too. Being on that end of it is a very frustrating experience.

But let's now balance that against the assumption at the other end of the spectrum: that an extensive code base, developed by competent engineers doesn't need simplifying or rewriting in a simpler way. As it turns out, this too, is a flawed assumption.

The more code I've seen, the more I've seen that most codebases that have survived any length of time are a mix of both, and it's hard to figure out what is what until you get some deep experience with it yourself. If there's been turnover in the team and the code has been under heavy churn, it's probably a mix of everything!

Re: Code only says what it does

#108

Post by ekimekim »

ChrisMarshallNY wrote: post #85
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…

That's exactly what I do. Why is a lot more important that what . Here's an example I use (Verbatim from here[0]): - Why Vs. What I’ve come to realize that the most important inline documentation concerns WHY we are doing something; not WHAT we are doing. For example, no one wants to read “// Set the value of b to 3,” for a line of code that looks like let b = 3. That’s just dumb. let b = 3 // Set the value of b to 3…

Or perhaps even better:

let iterations = 3 // We need to iterate 3 times for the value to stabilize

Re: Code only says what it does

#109

Post by thdrdt »

ekimekim wrote: post #108
ChrisMarshallNY wrote: post #85

Earlier quoted context omitted.

That's exactly what I do. Why is a lot more important that what . Here's an example I use (Verbatim from here[0]): - Why Vs. What I’ve come to realize that the most important inline documentation concerns WHY we are doing something; not WHAT we are doing. For example, no one wants to read “// Set the value of b to 3,” for a line of code that looks like let b = 3. That’s just dumb. let b = 3 // Set the value of b to 3…

Or perhaps even better: let iterations = 3 // We need to iterate 3 times for the value to stabilize

Yes, I think your example is better because "// Set the value of b to the number of iterations we'll be making" is almost the same as "/ Set the value of b to 3" when the code explains that `b` is used for the iterations.

Re: Code only says what it does

#110

Post by thdrdt »

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…

"...an excuse to comment rarely"

Well you can also look at it from another angle: unnecessary comments are a distraction and make code less readable.

You are not writing comments just to comment. You write them to make things clear.

Sometimes I also write comments to explain what, but most of the time those are written in large peaces of logic with multiple steps that cannot (or should not) split into multiple functions. But even then those comments tend to be in the form of 'why'.

For example: "// First we do this // Then we do this because.. // And as last step we do this because..."

My personal rule for comments:

If I come back in half a year, would I still understand what is going on here? No? -> Comment!

Post reply on HN