On 2020-04-23, Aisha Tammy <open...@aisha.cc> 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.
