Excellent comment and I fully agree with almost everything. Just one tiny nitpick:
For example if I have some sort of complex calculation, but it’s based on a well known algorithm, I might comment the name of that algorithm.
Unless you really need this complex calculation to be inline (e.g. for performance reasons) it would be better to move it into a function or method and include the algorithm in the name instead of adding a comment.
Very good! Your spidey senses are working perfectly. Hey I want to comment this calculation, why don’t I move it into a function so the name can explain what it does. Good call!
Sometimes the algorithm is inlined for performance, sometimes it’s a class with a bunch of functions that as a whole is primarily based on an algorithm, so comments might make sense in those cases. Most of the times it’s a library, so the name of the library kinda gives it away and hopefully has good documentation as well.
Excellent comment and I fully agree with almost everything. Just one tiny nitpick:
Unless you really need this complex calculation to be inline (e.g. for performance reasons) it would be better to move it into a function or method and include the algorithm in the name instead of adding a comment.
Very good! Your spidey senses are working perfectly. Hey I want to comment this calculation, why don’t I move it into a function so the name can explain what it does. Good call!
Sometimes the algorithm is inlined for performance, sometimes it’s a class with a bunch of functions that as a whole is primarily based on an algorithm, so comments might make sense in those cases. Most of the times it’s a library, so the name of the library kinda gives it away and hopefully has good documentation as well.
i want it in a function
fully include the pre implementation long hand in comments and the book / expert reference
the number of times i’ve found longer algos not doing as advertised is scary
improperly used statistical algos given the data sets and hand waving results are so common
gee i wonder why testing shows no improvement