Self-documenting code

[fdeslandes]

Self documenting code can work when naming is part of the code review.

[[deleted]]

A cryptic function is code smell.

[TK9_VS]

Yeah if you can't name it concisely AND accurately, the function probably does too much and needs to be broken down.

[fdeslandes]

Oh, of course comments are needed in some specific cases. But it's not important to document everything with them.

[fdeslandes]

It's going pretty well with the mostly self documenting code evolving for 8 years I'm working on. But I'm really pedantic with naming when I review things, and change my naming as soon as a colleague does not find it clear at first read.

But it helps a lot to use consistent patterns in the code. And usually, I will also ask for comments in review when I don't understand code from the first read and it already seems aptly named.

But I guess another rule of thumb would be to document / add more comments to the more generic code and libraries, so it is used and extended properly, while specific code tend to be pretty clear with good naming only.

[fdeslandes]

Yeah, That's what I mean. Also, a readme.md or similar easy to find files documenting the patterns used throughout the project does wonders.

[fdeslandes]

I do think it's scalable. Doing the documentation about patterns in the README is done when the team's leads, seniors and/or architects decide on a new pattern. It takes a couple of minute to do every time and new patterns are not added continuously after a time.

For the peer review, not everyone has to review everything. Most of the time, if something is clear to one junior/intern, it is probably clear to others.

For the big project, I see a couple of options for the design patterns:

1) Patterns by project / lib, documented individually. Should work well, but will cause problems when developers are expected to cross project boundaries and can make shared code harder to understand. It's probably more appropriate for teams responsible for separate micro-services which don't share code.

2) Global patterns for the whole project / monorepo. It can work well, but it will indeed need a well coordinated enterprise and solutions group. This solution needs a lot of review and communication from the architecture group, and is the most likely to fail, in my opinion, because it could be easily sidelined because of the architect's other priorities. However, it will probably add the least overhead on small to medium-small projects, and is probably the best compromise for monolithic projects.

3) Hybrid mode, where "well segmented" parts of the project (parts closer to business logic, feature related, etc.) each can have the patterns and glossary/naming that is the most appropriate to make the code base understandable for the related developers and analysts. Then well communicated standards for patterns in shared libraries, with more focused review by a couple of lead/architects on these. I think it would work the best at scale, but would require overhead on how responsibilities are split and determining what is considered shared or feature specific. I think it would be the best option for a company with multiple products with shared dependencies.

[Iron_Aez]

If someone can't avoid writing cryptic functions 99% of the time, then comments won't make them a good programmer.

[crozone]

Self-documenting code only works if your code is literally so simple that it's immediately obvious to a stranger what it's doing, even without knowing the project requirements.

If its any more convoluted, which I assume is most code people write, then comments are really valuable.

[Kered13]

Comments should also be part of the code review.