19
\$\begingroup\$

I'm surprised I can't find this as a question already, so I'm taking a shot and posting...

I document my code. I don't not document my code before considering myself done for the day. Most of the code posted here lacks documentation, and I'm trying to determine if it's an unofficial practice to strip things like doxygen comments or if it's simply undocumented code.

In short: Is it a best practice to include things like function documentation and inline comments when posting code for review?

\$\endgroup\$
3
  • \$\begingroup\$ Always include everything as it is for the review. What is documentation though? programmers.stackexchange.com/a/254979/125931 \$\endgroup\$
    – Raystafarian
    Jul 11, 2018 at 6:30
  • \$\begingroup\$ @Raystafarian Thank you for the link. It bears reminding that self-documenting code with a short description is better than a thousand words of explanation and some spaghetti code. \$\endgroup\$
    – jonspaceharper
    Jul 11, 2018 at 11:42
  • \$\begingroup\$ 1) Personally I leave the documentation in, having the right amount of comments (i.e., documenting things you should, without describing the code to the point where you are creating a bigger maintenance burden) can be tricky to master and I like to hear people's feedback on that, 2) When I include comments for CR reviewers only (e.g., directing them to something) I've done something like //@CR: Would you rather I wrote this using <method X> instead? \$\endgroup\$
    – jrh
    Jul 13, 2018 at 19:05

2 Answers 2

Reset to default
33
\$\begingroup\$

Is it a best practice to include things like function documentation and inline comments when posting code for review?

If you normally document your code, then include the documentation when posting here.

If you normally don't document your code, then don't add documentation just for the sake of posting it here.

We prefer to see the code as it was written.

It is however a good idea to make a self-review of your code before posting it here, and if you during that step find out that documentation is missing, well... then add some.

\$\endgroup\$
2
  • \$\begingroup\$ That's well put and a fair point. \$\endgroup\$
    – jonspaceharper
    Jul 9, 2018 at 10:34
  • \$\begingroup\$ Since this is from a mod, I'm going to accept. \$\endgroup\$
    – jonspaceharper
    Jul 9, 2018 at 10:38
18
\$\begingroup\$

Going purely from subjective impressions and without actually checking them, quite a lot of my answers specifically point out parts of the code which I think are underdocumented. There are at least two good reasons for leaving the documentation in:

  1. We want to review your actual code, not a sanitised version of it. Otherwise we might waste our time suggesting improvements which were already present in the real code.
  2. The better we understand your code, the more specific we can be in our reviews.
\$\endgroup\$
2
  • \$\begingroup\$ I admit this is the consensus I hope the community agrees upon, despite what it says about general documentation habits among programmers. \$\endgroup\$
    – jonspaceharper
    Jul 9, 2018 at 10:32
  • 6
    \$\begingroup\$ And perhaps 3. We might spot an error in the comments. \$\endgroup\$
    – Andrew Morton
    Jul 12, 2018 at 15:43

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .