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

51–60 of 71 posts

Re: The Shapes of Code

#51

Post by nerdponx »

clarry wrote: post #49
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.

const database_year_offset = 7; fix_start_year(year): return year + database_year_offset; process_record(record): record['start year'] = fix_start_year(record['record']); In this version with one less magic constant (and renamed function), the comment would look very redundant. DougBTX had the same idea, at the same time. I don't think their version needs the comment either. EDIT: Dang you removed a perfectly fine po…

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?

Re: The Shapes of Code

#52

Post by clarry »

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.

I see a lot of this at work, sigh.

The better a variable / function is named (and the better its scope or purpose is limited to one thing), the less it needs comments. So there are a lot of self explanatory variables or functions with doxygen comments that state exactly the same thing the name already does, without adding anything besides noise. And then there are some poorly named things where the exact same thing happens: comment re-states what the bad identifier states. Sigh. Genuinely useful comments are rather rare.

Re: The Shapes of Code

#53

Post by clarry »

nerdponx wrote: post #51
clarry wrote: post #49

Earlier quoted context omitted.

const database_year_offset = 7; fix_start_year(year): return year + database_year_offset; process_record(record): record['start year'] = fix_start_year(record['record']); In this version with one less magic constant (and renamed function), the comment would look very redundant. DougBTX had the same idea, at the same time. I don't think their version needs the comment either. EDIT: Dang you removed a perfectly fine po…

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.

Re: The Shapes of Code

#54

Post by SketchySeaBeast »

swish_bob wrote: post #39
AstralStorm wrote: post #35

Earlier quoted context omitted.

The code might be obvious, but if you don't include the reason why it exists it's a target for removal. And having too many of those makes either for garbage or hard decisions when refactoring. Writing the rationale is the most important comment you must not skip. And there would be links to design documentation so that it can be kept up to date. (For non-programmers.)

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.

Does that explain why, though? It explains that it's there, and someone obviously wanted it to be, but it still doesn't get at the why. I've found that most of the logic I'm left scratching my head at is due to some business rules that there's no better way to deal with - even if a test exists for it I still can't figure out what the tests purpose was, other than to just verify that it's working.

Re: The Shapes of Code

#55

Post by Firadeoclus »

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.

Factoring out a comment into code sometimes loses information. I would argue that database_year_offset is not as informative as the original comment. Free form text can say things better than identifier names.

Re: The Shapes of Code

#56

Post by hinkley »

rgoulter wrote: post #22
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.

I can agree "code should be in small functions" by itself is a bad guideline. I think it's suggested due to other principles around making code easier to read / use. It'd be better to ask if the code is more complex than it needs to be. I liked the terms John Ousterhout uses. For some module of a program (e.g. a method, class, package, etc.), it has an interface and an implementation. The interface is "what you need…

In most cases one big method is an increase of complexity (and others will add to it over time). Large methods are usually a failure of imagination, like bad and rambling prose.

Code is a set of instructions for the computer, and for the next person who has to maintain it (“ Programs are meant to be read by humans and only incidentally for computers to execute.”)

Cooking instructions are split into steps. Assembly instructions are split into steps. LEGO instructions are split into steps. When drawing instructions aren’t split into steps the Internet turns them into a cultural phenomenon (Step 2: draw the rest of the fucking owl).

Only programmers think they are immune to this ridicule, smash all the steps together, and then get salty when others complain, ignoring a series of luminaries who beg in every format of media available, and for decades, to do otherwise.

Seriously, organize your code, separate the steps. You’re killing us.

Re: The Shapes of Code

#57

Post by BitwiseFool »

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.

We typically use comments to describe our client's business process. Even though the code itself looks straightforward what the client wants certainly isn't.

Re: The Shapes of Code

#58

Post by mason55 »

hinkley wrote: post #56
rgoulter wrote: post #22

Earlier quoted context omitted.

I can agree "code should be in small functions" by itself is a bad guideline. I think it's suggested due to other principles around making code easier to read / use. It'd be better to ask if the code is more complex than it needs to be. I liked the terms John Ousterhout uses. For some module of a program (e.g. a method, class, package, etc.), it has an interface and an implementation. The interface is "what you need…

In most cases one big method is an increase of complexity (and others will add to it over time). Large methods are usually a failure of imagination, like bad and rambling prose. Code is a set of instructions for the computer, and for the next person who has to maintain it (“ Programs are meant to be read by humans and only incidentally for computers to execute.”) Cooking instructions are split into steps. Assembly in…

No one disagrees that code needs to work in steps. The conversation is around how much and the answer is going to depend on what you're doing.

Why have a function that prints a whole line? Isn't that just smashing together a bunch of small steps to print one character at a time?

Post reply on HN