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

31–40 of 71 posts

Re: The Shapes of Code

#31

Post by artsyca »

CraigJPerry wrote: post #26
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.

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.

It's definitely the why for any particular unorthodox bits like shims hacks workarounds and the like

The worst is finding some snippet from stack overflow or GitHub without a reference to the issue to back up why this thing is here or perhaps a TODO: with an improvement

Re: The Shapes of Code

#32

Post by goto11 »

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.

Maybe because some people have learnt they should comment but haven't learnt how to comment properly. And as often the case in this industry, the fact that some people do some thing badly leads other people to forbid the thing altogether.

Re: The Shapes of Code

#33

Post by classified »

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.

I'm not sure whether I should envy or pity you. Writing code that is that obvious and boring cannot be very fulfilling. How long until a machine does that for you (after all, automating boring and obvious stuff is what we programmers do)? OTOH, on days where I feel lazy I can only wish my world were that simple.

Re: The Shapes of Code

#34

Post by lincpa »

The data flow programming of pure pipeline structure, It systematically simulates integrated circuit systems and large industrial production lines.

In the computer field, for the first time, it was realized that the unification of hardware engineering and software engineering on the logical model.

It has been extended from Lisp language-level code and data unification to system engineering-level software and hardware unification.

and it brings large industrial production theory and methods to software engineering. It incorporates IT industry into modern large industrial production systems, This is an epoch-making innovative theory and method.

This is the [Pure Function Pipeline Data Flow v3.0 with Warehouse/Workshop Model](https://github.com/linpengcheng/PurefunctionPipelineDataflow).

Re: The Shapes of Code

#35

Post by AstralStorm »

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.

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

Re: The Shapes of Code

#36

Post by RickJWagner »

I'm a software maintenance engineer. I make my living reading other people's code and trying to internalize it so I can make repairs where they are needed.

This is an interesting article, and I intend to go listen to the podcast, too.

In the past I've made efforts to try to speed up the process of learning a codebase. I'd do things like copy the code into a text processor, then shrink the font so I could see which files (classes) were biggest, and look for repeating shapes like the author mentions. I'd also use code cleaners to point out troublesome classes and UML full-trip tools to try to get a good sequence diagram out of a piece of code.

It was all cumbersome, unfortunately. Most days I just use 'grep' to help me figure things out. I'm still looking for helpers, though. I'm hoping the podcast helps.

Re: The Shapes of Code

#37

Post by Izkata »

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.

You left out the most important part of this criticism:

> ...to explain each line of code.

Commenting every line is a hint to a more pervasive problem. This section has nothing to do with "comments are bad".

Re: The Shapes of Code

#38

Post by nerdponx »

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.

    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.

Re: The Shapes of Code

#39

Post by swish_bob »

AstralStorm wrote: post #35
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.

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.

Re: The Shapes of Code

#40

Post by taneq »

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.

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.
Post reply on HN