Thanks a lot for responding, I've had some food so am feeling a lot less frustrated :D
> On 4/23/20 12:10 PM, Stuart Henderson wrote: > > It's often considered better if code is clear enough to stand by itself, > keeping comments for the less common cases which can't be figured out > from reading the code. And that way you aren't at risk of assuming But like, not all code is simple enough to understand by just reading it. Comments can do more than just explain api, they can help explain how the code itself is working. I have been reading diff, sdiff diff3 and other string algorithms to understand how to make it as fast as their GNU counterparts and they are not the simplest to read, even when knowing the actual string algorithms pretty well. > something which is implied by the comment but isn't actually in the code > (either never was, or the code changed but the comment didn't keep up). > And about comments being left behind in code changing, I feel like that is easily changed by people making sure that they also read comments while coding. I don't think that is a good enough excuse about not commenting. > If you aren't already, you should be looking at commit messages from > where the relevant code was touched. That is often where you'll find the > explanations you seek. > I have been reading them, Commit messages don't explain algorithms very clearly. I agree this is a very specific use case but definitely something that could be improved. Some of the things I've been considering useful (in this specific scenario for diff3) - explanation for merge function, what it does - in merge function, explain how empty for loop is used, as this is a very big loop with a lot of cases IMO, any function with a lot of cases should have a small explanation about what it is doing, so the code is a lot more lit. Cheers, Aisha
