Re: Comments in source code
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 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
Re: Comments in source code
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
Re: Comments in source code
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
Re: Comments in source code
On Thu, Apr 23, 2020, at 5:38 PM, Aisha Tammy wrote: > > 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 I am no expert on reading code myself, but wouldn't be possible to look at who wrote that bit of code find their email address and ask them? There might not be a simple terse explanation that would go well in comments.
Re: Comments in source code
On 2020-04-23, Aisha Tammy wrote: > Hey devs and all, > I'm kind of new to OpenBSD, only working on ports so far so take > what I say with chill. > I've been reading the source code in GIT and felt a real lack of comments > explaining what the code is doing. Is this something encouraged in obsd? > I would really like to have something more than super condensed one line > explanations like in style(9). > > Just wanted to express my frustration and also to ask if there is any > better way to understand how the code is working? I feel like this > would deter a lot of new contributors, me including. > > Hopefully I don't sound too negative. I'm willing to send patches which > just add comments and explanations, if there is any interest from the devs. > > Best, > Aisha > > 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 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). 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.
Comments in source code
Hey devs and all, I'm kind of new to OpenBSD, only working on ports so far so take what I say with chill. I've been reading the source code in GIT and felt a real lack of comments explaining what the code is doing. Is this something encouraged in obsd? I would really like to have something more than super condensed one line explanations like in style(9). Just wanted to express my frustration and also to ask if there is any better way to understand how the code is working? I feel like this would deter a lot of new contributors, me including. Hopefully I don't sound too negative. I'm willing to send patches which just add comments and explanations, if there is any interest from the devs. Best, Aisha
