In computer programming1, code smells are “surface indications that usually correspond to deeper problems in the system”. Duplicated code is one example. Copying a code fragment into many different places is generally considered bad form; Don’t Repeat Yourself is a well known principle of software development. However, duplicating code can be beneficial if, say, it makes the code easier to read and maintain.
Although code smells are undesirable, “they are not technically incorrect and do not prevent the program from functioning.”
By this description, I’d argue that smells also exist in scientific papers. Hence, I’m proposing a few of these easy-to-spot (aka sniffable) features that may point to a deeper underlying issue.
The Supplementary Material is long
Supplementary Material provides a place for details that are not central to the main story. It should not be used as a dumping ground for analyses and figures that didn’t fit in the main paper.
The paper is just below the length limit
A paper should have as many words, figures, and tables as it needs to make its point. Of course, journals do impose a limit. If the paper is brief—great. If it’s way too long, you’ll have to make wholesale changes or submit to a different journal. But if you’re just over the limit, then you might go back and tighten up your writing. Or you might be tempted to cut certain details or employ every editing trick there is and actually make the paper worse.
The abstract is just below the word limit
This is the previous rule writ small. Take, for example, an abstract that is 248 words long. Is it this long because that’s simply how long it needs to be, or because the author added as many details as possible until they hit the externally imposed limit of 250 words?
The paper ends by highlight what is not known
It’s common to conclude a paper by suggesting questions for future work. Is this because the paper actually opened up new, fruitful avenues for future research? Or is it because the paper lacks enough substance to finish on a positive note? A conclusion should highlight what has been contributed to scientific knowledge, not what hasn’t.
Too many similar looking figures
Scientific papers can be thought of as the curation and distillation of a dataset. They are not the place to dump every bit of data. To this end, be wary of figure captions that fit the following template: “Figure 4: Same as Figure 3, but . . .“. In some cases, this format might be valid; in others, it might be laziness.
Too many section headings (or levels of headings)
Sections and section headings help organise a paper and make it skimmable. These are good things, when done properly. But too many sections can cause fragmentation and dilute their organising effect. Unless you’re writing a book, avoid three levels of heading (e.g., Section 4.1.2).
Figure 1 is meaningless without context
People are going to skim your article. The first figure they see should be easily grokked and give them a taste of what the paper is about. It could be a map of the study site, a schematic, or a picture of the main instrument. It shouldn’t jump straight to, say, a line graph of some complex or abstract quantity. That’s for later in the paper after you’ve built up to it.
Needing a laser pointer (a smell for scientific talks)
The problem with laser pointers isn’t the laser pointer itself. Rather, needing one can be a symptom of poor preparation. Many slides should be simple enough that the audience only has one thing to look at. More complicated slides can be built up incrementally to ensure the audience knows where to look.
Smells are only smells
A smell is a hint that something may be wrong. “Calling something a smell is not an attack; it’s simply a sign that a closer look is warranted.”
Footnotes
1Computer programming is full of descriptive and sensory metaphors:
Dogfooding – using your own products (e.g., a spokesperson for a dog food company feeding their dog the same product).
Bike-shedding – focusing on trivial details rather than the bigger picture (e.g., when discussing a proposal for a nuclear power plant, focusing on the staff bike shed).
Truck factor – The number of people on your team who have to be hit with a truck before the project is in serious trouble.
Brushing Up Science 