Pretty much this. I am a huge supporter of "useful documentation" but over 90% of what I read either code, techbooks, manuals, the list goes on is written by people who don´t know how to do it properly.
OpenBSDs code is clean though as far as I can judge. I read through the whole thing simply for educational purposes and it was a wild ride I have learned a lot doing it and forgot a lot again but it was nice and it´s not often nowadays that you read code and can be quite certain that it is "written to work" and not written to be patched, hotfixed, savaged and whatnot. Read it, understand it, follow @tech and maybe there is a chance to start a discussion about something you understood and don´t agree with. So far I am reading @tech for like 2years, understand a few things and get lost on a lot of things but it´s mostly educational. :) _______________________________ Always exit with 42 to return the answer. ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Friday, 24. April 2020 07:36, Chris Bennett <cpb_m...@bennettconstruction.us> wrote: > 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
publickey - flauenroth@protonmail.com - 0xD727BBC1.asc
Description: application/pgp-keys
signature.asc
Description: OpenPGP digital signature
