back

by jasonpeacock·6y ago·view on hn ↗
You're describing self-documenting code. Well written code shouldn't require any "what" comments, only "why" comments.

Too often you see code with a generically-named function/variable, and a comment next to it describing what it does. Why not just name the function/variable correctly?!

There's a strong cargo-cult idea that "real" programmers use short/abbreviated names, and yet there's absolutely no value to using "idx" over "index", or a more appropriately named "last_name_index".

1 comments
Naming is always hard, but sometimes the "what" requires a full paragraph, and even very long variable names shouldn't exceed 80 characters all on their own.

torque_aux_motor_braking_only_safety_threshold_nm is a good variable name, but I wouldn't want to let them get much longer than that.