search

NBISweden / development-guidelines

Development guidlines for software within NBIS.
GNU General Public License v3.0
16 stars 8 forks source link

stricter comment guidelines #40

Closed norling closed 3 years ago

norling commented 3 years ago

Makes commenting guidelines a bit stricter, and adds references for commenting guidelines.

danr commented 3 years ago

I kind of have the opposite approach to comments as the change you have made. I would say that it should be obvious what the code does and also why, but if why is surprising it is appropirate with a comment.

On the other hand I think it's very nice to document code with doctests. This will describe at least what the API does if not the code itself.

norling commented 3 years ago

Yeah - I know from our previous discussions. My experience is that your way (without comments) is way too much work though. I've been in a few projects that use self-explanatory code, and I've never seen it work. It also implies the question "who should understand the code?". Like - you can't assume that whoever looks at the code is particularly experienced in either the programming language or the libraries/frameworks that are used? So you'd have to write code that's completely devoid of advanced language constructs or non-obvious framework/library functions for it to maintain readability... It seems like it would be a lot easier and a lot less work to just summarize what the function does and what inputs/outputs it has.

pontus commented 3 years ago

For clarity - I think inline documentation should be there in languages where that's supported, so to me, these "comments" I think of is other comments.

danr commented 3 years ago

So what should I do if i disagree? Approve or reject? :thinking:

jhagberg commented 3 years ago

So what should I do if i disagree? Approve or reject?

Reject I guess and then we see if we get a majority. This is just recommendation so you can later just ignore them in your day to day work

norling commented 3 years ago

Dan - I agree, reject this, and if you want you can make your own PR :) Might be that we should discuss this a bit more somewhere to see what opinions people have. I'm mostly just trying to figure out what I'd want if I were to look at an unfamiliar codebase... But there's probably a case to be made for focusing on convenience as well!

norling commented 3 years ago

Good point! :) I'll read and think and try to differentiate between documentation and commenting to make the guidelines clearer.