45 ms·

I think people often lean too far in favour of "self-documenting code," and "what" comments wind up being underused. The idea of self-documenting code is that t

by bccdee 5y ago

I think people often lean too far in favour of "self-documenting code," and "what" comments wind up being underused. The idea of self-documenting code is that the documentation is encoded in the function and variable names, more or less. Sure, extraneous comments should usually be avoided, but frankly, sometimes a couple sentences of plain English is just clearer. I'd rather people just tell me what's going on than try to squeeze it in to a few camel-case words if that would compromise the clarity.

patrick451 5y ago
When your coding standard enforces 80 characters, you end with a single logical statement split across many lines. This quickly approaches un-readability if you fetishize self documenting code. In my opinion, short variable and function names with a comments are often more readable that self documenting behemoths, e.g., double compute_angular_acceleration_in_radians_per_second_per_second(double torque_in_newtons_per_meter, double moment_of_inertia_in_kilogram_meters_meters); vs // Units are base unitsSI. double compute_angular_accel(double tau, double J); I'll take the second any day.
- pydry 5y ago
  What about the day the Mars climate orbiter was lost because one piece of code wrongly assumed that the units of figures out of the other piece of code? :) I find that you do sometimes need symbol names that long even though it's a code smell indicating something else is up - usually scopes that are too large or insufficiently expressive types. I view excessively long variable names as a midpoint on a journey to improving code quality on really bad code bases.
  - adrian_b 5y ago
    While what you say about long variable names can be right in certain circumstances, the example with the wrong units is inappropriate. In my opinion any code that deals with physical quantities, but which does not use dedicated types for each kind of physical quantity, where the type definitions include the units used, is erroneous. Any mistake like in the Mars orbiter must be detected at compile time.
- bccdee 5y ago
  It's also substantially easier to update a comment, making it more descriptive, than it is to update a variable name.
taneq 5y ago
It's much easier to fool yourself into thinking you're writing "self-documenting code" if your "documentation" is just a natural language rephrasing of your code.

by bccdee 5y ago

patrick451 5y ago

When your coding standard enforces 80 characters, you end with a single logical statement split across many lines. This quickly approaches un-readability if you fetishize self documenting code. In my opinion, short variable and function names with a comments are often more readable that self documenting behemoths, e.g., double compute_angular_acceleration_in_radians_per_second_per_second(double torque_in_newtons_per_meter, double moment_of_inertia_in_kilogram_meters_meters); vs // Units are base unitsSI. double compute_angular_accel(double tau, double J); I'll take the second any day.

pydry 5y ago
What about the day the Mars climate orbiter was lost because one piece of code wrongly assumed that the units of figures out of the other piece of code? :) I find that you do sometimes need symbol names that long even though it's a code smell indicating something else is up - usually scopes that are too large or insufficiently expressive types. I view excessively long variable names as a midpoint on a journey to improving code quality on really bad code bases.
- adrian_b 5y ago
  While what you say about long variable names can be right in certain circumstances, the example with the wrong units is inappropriate. In my opinion any code that deals with physical quantities, but which does not use dedicated types for each kind of physical quantity, where the type definitions include the units used, is erroneous. Any mistake like in the Mars orbiter must be detected at compile time.
bccdee 5y ago
It's also substantially easier to update a comment, making it more descriptive, than it is to update a variable name.

taneq 5y ago

It's much easier to fool yourself into thinking you're writing "self-documenting code" if your "documentation" is just a natural language rephrasing of your code.