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

The Shapes of Code

fluentcpp.com

Post reply on HN
Print view View original

61–70 of 71 posts

Re: The Shapes of Code

#61

Post by swish_bob »

minaa-chan wrote: post #46
swish_bob wrote: post #39

Earlier quoted context omitted.

Why it exists ought to be explained by the existence of a test. This isn't always possible, but it's far more possible than many developers seem to think.

That just makes two things that need to be commented doesn't it? When I read code I care about what the code is supposed to do and why it's supposed to do that. There is code that passes the current tests and is logically sound but no longer fits the business requirements. Knowing that it was implemented to solve a certain use case helps the reader / reviewer see whether the code and the test still fit or if they sho…

Your test should explain what it's testing. Via it's name or some other mechanism. Otherwise how do you know what's gone wrong when it fails?

Re: The Shapes of Code

#62

Post by reuben_scratton »

luckycharms810 wrote: post #3

While the patterns themselves are interesting, the idea that all code must be rearranged in to smaller functions to be “refactored” seems a little juvenile.

Absolutely this.

More functions => More complexity => Bad.

Also: decreased legibility, less opportunity for compiler optimisation.

Re: The Shapes of Code

#63

Post by thfuran »

clarry wrote: post #28
classified wrote: post #23

> ... not so good code: if it was, we wouldn’t need a comment... How much longer will this rumor persist that "good code" doesn't need commenting? Good comments explain things that aren't immediately obvious from the code.

Most code should be boring and immediately obvious. I don't run into lots of real world code that needs much explaining. Sometimes you do something weird or not-obvious for good reason, but I see plenty of comments explaining things that only need to be explained due to poor design. Also poor comments that don't really explain anything that isn't obvious by looking.

Just yesterday I wrote some code that was pretty boring, pretty readily understandable, and also pretty apparently a good target for an easy simplification. However that obvious simplification would also non-obviously introduce a bug that might not be noticed immediately. So I left a comment to the effect of "yeah these two lines look kinda dumb but we need it because X"

Could I have instead massively restructured the feature to prevent the possibility of the bug the comment was explaining the workaround for? Probably. But that would have increased the number of lines of code to make the change by a factor of something like 20x-200x and would have required far more testing. It also probably would have resulted in something overall more complicated.

Re: The Shapes of Code

#64

Post by nerdponx »

taneq wrote: post #40
nerdponx wrote: post #38

Earlier quoted context omitted.

def clean_start_year(x): # Account for the 7 year offset in the database return x + 7 def process_record(record): record['start year'] = clean_start_year(record['record']) It's perfectly obvious what this code does, but without the comment it's totally unclear why it does what it does.

Ah, the inline equivalent of Doxygen-for-the-sake-of-Doxygen documentation. int frob(const int x, void *context) Performs a frob on x in the given context. Parameters: x - int param context - a pointer to context Returns an id of the frob performed.

How is what I posted an example of this, in any way?

Use your imagination. The "cleaning" routine might not be a one-liner. Maybe it depends on multiple functions from another file/package/library.

Re: The Shapes of Code

#65

Post by CraigJPerry »

minaa-chan wrote: post #47
CraigJPerry wrote: post #26

Earlier quoted context omitted.

Like what? It can’t be the “how” - the code should be able to express that clearly. It can’t be the “what”, again that should be apparent from some combination of code and configuration / metadata. So that leaves the “why”. To my mind, code comments are the worst place to record why a particular implementation exists. The why often needs collaboration with non-coders.

I disagree. The code is the best place to comment the why. Regardless of what is documented or what is written up on jira or w/e, the code is what is true. Commenting the purpose of the code and maybe a link to some documentation allows a future reader to see if the code still fulfills the requirements.

The comments are very often not true, that's why there's so much push back

Re: The Shapes of Code

#66

Post by minaa-chan »

swish_bob wrote: post #61
minaa-chan wrote: post #46

Earlier quoted context omitted.

That just makes two things that need to be commented doesn't it? When I read code I care about what the code is supposed to do and why it's supposed to do that. There is code that passes the current tests and is logically sound but no longer fits the business requirements. Knowing that it was implemented to solve a certain use case helps the reader / reviewer see whether the code and the test still fit or if they sho…

Your test should explain what it's testing. Via it's name or some other mechanism. Otherwise how do you know what's gone wrong when it fails?

That other mechanism is comments.

Re: The Shapes of Code

#67

Post by nerdponx »

clarry wrote: post #53
nerdponx wrote: post #51

Earlier quoted context omitted.

I guess, but I think it's more that my example fails to illustrate the point well. Informative comments cannot always be "factored out" like this. Do you at least agree that a ticket or bug #, or a link to an issue in an issue tracker, would be appropriate?

I think a comment is appropriate if the problem cannot be factored out. But in my experience such things can be factored out most of the time, hence the argument that most code should be boring and immediately obvious.

Most code, sure. But it's not an ideal to be striven for, or a metric to be used when evaluating code.

Re: The Shapes of Code

#68

Post by blakehaswell »

classified wrote: post #23

> ... not so good code: if it was, we wouldn’t need a comment... How much longer will this rumor persist that "good code" doesn't need commenting? Good comments explain things that aren't immediately obvious from the code.

> How much longer will this rumor persist that "good code" doesn't need commenting?

Indeed. I recently came across an article[0] which does a good job of debunking this idea, and describing different types of comments and when they can be valuable. Have a read if you're skeptical about comments.

[0] http://antirez.com/news/124

Re: The Shapes of Code

#69

Post by AnanasAttack »

nerdponx wrote: post #38
clarry wrote: post #28

Earlier quoted context omitted.

Most code should be boring and immediately obvious. I don't run into lots of real world code that needs much explaining. Sometimes you do something weird or not-obvious for good reason, but I see plenty of comments explaining things that only need to be explained due to poor design. Also poor comments that don't really explain anything that isn't obvious by looking.

def clean_start_year(x): # Account for the 7 year offset in the database return x + 7 def process_record(record): record['start year'] = clean_start_year(record['record']) It's perfectly obvious what this code does, but without the comment it's totally unclear why it does what it does.

The comment doesn't explain why there even is an offset in the first place. Who put it there and why? I think this should be explained as well

Re: The Shapes of Code

#70

Post by minaa-chan »

CraigJPerry wrote: post #65
minaa-chan wrote: post #47

Earlier quoted context omitted.

I disagree. The code is the best place to comment the why. Regardless of what is documented or what is written up on jira or w/e, the code is what is true. Commenting the purpose of the code and maybe a link to some documentation allows a future reader to see if the code still fulfills the requirements.

The comments are very often not true, that's why there's so much push back

So they should be updated the same as any other documentation. They're there to help. They don't need to be 100% infallible to be useful.
Post reply on HN