Hacker News Reader

Comment by urthor | Hacker News Reader

1. "Comments are bad" is bullshit.

Definitely put the comments in the docsting or equivalent for your language, not in the middle of the function.

The best place for comments is nicely grouped under (or above, an elegant C++ convention) the interface. If the function signature is 200 LOC away... the problem isn't the comments.

But they should be there.

2. People, need, diagrams. People NEED a picture.

At the minimum, the bare minimum, your application needs a high level and low level diagram explaining how it works.

View on HN

Diagrams have their place, and a high level diagram can be very useful, but I find that low level diagrams usually tend to be a lot more trouble than their worth. They get complex and both hard to understand and maintain, which means they tend to get ignored when changes happen and become out of date.

I've found that if I'm struggling to create a diagram for something in Mermaid then I've gone too deep in my explanations and it's time to step back.

Maybe I need a better way to phrase it.

High level architecture diagrams, user journey diagrams, low level diagrams, are probably all distinct topics.

I feel all three are extremely important, but that's bordering on my opinion.

> but I find that low level diagrams usually tend to be a lot more trouble than their worth

Out of date low level diagrams are surprisingly useful.

One of the things that I've found is that, with extremely high LOC projects (LOC definitely measures complexity), you'll find that low level diagrams are worthwhile, at the cost of a time investment in generating them.

When/how to do them is a certainly a fine art. There's no right answer.

It sounds like our experiences differ when it comes to low level diagrams. While I'm dealing with a lot of complexity in systems I'm developing, they don't tend to have a high number of lines of code - or at least they don't once we get the architecture right :)

Perhaps there is a correlation between complexity due to a high number of lines of code and benefits provided by low level diagrams. If there is then it does pose the question of when you should invest time in creating and maintaining low level diagrams and when it would be better spent reducing the size of the codebase.

I do not usually use diagrams. Therefore... I'm not a person? :)

Have pity on us mortals.

It your first week onboarding significantly easier in my experience, the first time I encounter a codebase. I'm sure people make do without.

Lotta science behind it, humans work much better if there's a diagram with coloured shapes/lines involved.

Reply on news.ycombinator.com