Peer Review Etiquette: When to Speak Up About Code Quality
You're knee-deep in a paper, slogging through the math and code that underpins it. As a peer reviewer, you're there to provide constructive feedback and help the authors improve their work. But when you come across some pretty rough code, do you call out the messiness or politely let it slide? We've all been there: staring at a wall of cryptic variables and wondering how anyone could have written such a thing. Yet, it's your job to point out the problems and help the authors fix them.
So, should you comment on the authors' messy code? The answer is yes, but with caution. You're not there to criticize the authors personally, but to help them improve the clarity and reproducibility of their research. When providing feedback on the code, focus on how it affects the overall quality of the paper rather than making personal attacks.
Here are a few tips to keep in mind when commenting on code quality during peer review:
- Be specific: Instead of saying "this code is a mess," point out specific issues, like inconsistent indentation, unclear variable names, or missing comments.
- Focus on the impact: Explain how the code quality affects the reader's ability to understand and replicate the results. For example, "I found it difficult to follow the computations in Section 3 due to the lack of clear variable names."
- Suggest improvements: Offer concrete suggestions for how the authors can improve the code, such as using a consistent naming convention or adding comments to explain complex sections.
Let's take an example from the context of your paper. You're reviewing a paper in pure mathematics that relies heavily on computer computations. The authors have provided a link to the Magma code they used for most of these computations, but it's a nightmare to navigate. You might write a comment like this:
I found the code to be difficult to follow due to the lack of indentation and unclear variable names. For example, the variable 'aaa' is used in several places without explanation of its purpose. I would suggest using a consistent naming convention and adding comments to explain complex sections. This would make it much easier for readers to understand and replicate the computations.
Remember, your goal is to help the authors improve their work, not to criticize them. By providing specific, actionable feedback, you can help them create a better, more reproducible paper that will benefit the entire field.