Post #1263558

2026-04-17 15:48 UTC

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.

Replies (2)

@baines@lemmy.cafe 2026-04-17 16:38

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

Open ##1266077
@Thorry@feddit.org 2026-04-17 17:35

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.

Open ##1269164