On Thu, Apr 23, 2020 at 05:38:40PM -0400, Aisha Tammy wrote: > 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. >
If reading the code isn't enough and you see parts you don't understand, then break those parts. See what happens. Find out why it was done. You might find out that the code at that spot doesn't even work correctly. You might figure out a way to fix it or eliminate it. Perhaps submit a diff. >From your work, you may be able to ask a very specific question. Specific questions are more likely to be answered. If someone knows the answer AND also has the time and desire to help. You may also find that the old way was great back in older versions of OpenBSD, but no longer the best way due to changes in the OS. > > 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 > Are you reading commit messages far enough back in time? OpenBSD is a fork of NetBSD. Maybe you will need to go back much further in time to find the commit message or discussion that lead up to today. I strongly support comments, very strongly. But only when needed. Explanations are better coming from someone who can discuss with you or might only be available from you working it out for yourself. This is a volunteer project. Comments don't get compiled, but they do take up space, disk space and bandwidth space. Have fun, work hard and enjoy yourself. There are some excellent threads about these topics in the mailing lists. Chris Bennett
