Settings

Theme

Eloquent code needs no comment

alexis.bernard.io

3 points by a12b 2 years ago · 2 comments

Reader

samsquire 2 years ago

For me, personally, I can read a sentence in my English more easily than code. Code takes more effort for me to read, especially if it's not mine.

Don't tell me what the code is doing, tell me what you're trying to achieve. The goal you're trying to achieve. Tell me the problem and the outcome you want. Then I should read the code with a target understanding in mind rather than starting from nothing.

My mental model of how things work might be different to yours and you need to transfer that mental model to me so I can understand your code.

Context is everything when reading a line of code. Context of the business, context of state of the program, context of variables. Context of microservice state. Context context context.

KingOfCoders 2 years ago

Every code needs comments. Not the WHAT (Here we add a and b - I can read the code!) but the HOW (We use Quicksearch here) and the WHY (We do X instead of Y because ABC or feature X1 or ...).

Keyboard Shortcuts

j
Next item
k
Previous item
o / Enter
Open selected item
?
Show this help
Esc
Close modal / clear selection