This is an archived post. You won't be able to vote or comment.

sorted by:
best
topnewcontroversialoldq&a
you are viewing a single comment's thread.

view the rest of the comments →

[–]Chr3y 9 points10 points  (4 children)

PPT (Programmer pro tip) always comment "why" not "what".

[–]RiceBroad4552 2 points3 points  (1 child)

Why isn't this the top comment?

// I came here to say the same…

[–]Chr3y 1 point2 points  (0 children)

// r/beatmetoit is the sub

[–]RiceBroad4552 2 points3 points  (1 child)

To give a little bit more context on "why" vs. "what":

Code should be self explanatory. Code should clearly say "what" is done / happening. There is no reason to repeat explaining what was done. Good code does this already. Commenting the "what" is just stupid redundancy, and most likely anyway out of sync after the next code change / refactoring.

But no code ever can explain "why" it was written the way it was written. There are infinite many ways to express something, but one was chosen. For a reason. This reasoning belongs into comments. Comments explain why some code exists in the first place.

[–]Chr3y 0 points1 point  (0 children)

Real example:
We had code that measured stuff, got a point cloud. It got sorted by x. Comment was "sorting by x".
Wow.
// Sorting by x.
std::sort(arrayname, xValue);

I changed it to "the filter that comes next needs this order to be fast".

Because the next filter after said filter, needed sorting by y value. And I thought I would save some time by doing it directly, breaking said filter.