Are comments discouraged in a BibTeX file?

Question

biber complains about "junk" in what should be seen rather as commented-out lines in a BibTeX file. I was wondering if comments are discouraged in BibTeX at all.

\documentclass {article}

\usepackage {filecontents}

\begin {filecontents} {ref.bib}
 @book {book1,
 author={author 1},
 title={title 1}}

 book {book2,
 author={author 2},
 title={title 2}}

 @book {book3,
 author={author 3},
 title={title 3}}
\end{filecontents}

\usepackage [backend=biber] {biblatex}
\addbibresource {ref.bib}

\begin {document} 
 \nocite{*}
 \printbibliography
\end {document}

Here is biber's output:

INFO - This is Biber 2.1
INFO - Logfile is 'mwe.blg'
INFO - Reading 'mwe.bcf'
INFO - Using all citekeys in bib section 0
INFO - Processing section 0
INFO - Looking for bibtex format file 'ref.bib' for section 0
INFO - Decoding LaTeX character macros into UTF-8
INFO - Found BibTeX data source 'ref.bib'
WARN - BibTeX subsystem: /tmp/No7MbpTruX/ref.bib_31209.utf8, line 13, warning: 43 characters of junk seen at toplevel
INFO - Overriding locale 'en-US' defaults 'variable = shifted' with 'variable = non-ignorable'
INFO - Overriding locale 'en-US' defaults 'normalization = NFD' with 'normalization = prenormalized'
INFO - Sorting list 'nty' of type 'entry' with scheme 'nty' and locale 'en-US'
INFO - No sort tailoring available for locale 'en-US'
INFO - Writing 'mwe.bbl' with encoding 'ascii'
INFO - Output to mwe.bbl
INFO - WARNINGS: 1

Answer 1

It is in no way discouraged to comment any files you might have written. What you came across is a slight discrepancy in the handling of comments, or if you will a disagreement about what constitutes a comment.

According to btxdoc, §4, item 7, p. 13

BibTeX allows in the database files any comment that's not within an entry. If you want to comment out an entry, simply remove the @ character preceding the entry type.

That means that anything that is not within a @<entrytype>{...} entry block has to be considered a comment by the parser.

Furthermore, in §4, item 14, p. 14, we find

LaTeX's comment character % is not a comment character in the database files.

So technically (and legally, if you will) your block with book2 is indeed a comment.

Still, Biber warns about it mentioning "characters of junk". You can safely ignore this warning just as Biber ignores these characters. Instead you can see these warning as an additional service by Biber to warn you that something might be wrong. Sometimes people genuinely forget a @ or have some real junk in their files.

Contrary to the excerpt quoted above, Biber considers lines starting with % to be real comments and does not issue junk character warnings in these cases. So if you are OK with using % at the beginnings of comments in your .bib file, Biber will not bother you about them again, even though technically the lines outside a @ block should be considered comments without the % as well.

As biber considers % a real comment sign, it handles commented entries differently to BibTeX. An entry starting with

%@article{A,

will be ignored by biber (and the rest will junk), while bibtex will still see it.

Since the % is not considered a comment character by BibTeX, but is passed through verbatim to LaTeX (where it will be recognized as a comment with possibly catastrophic results), you should better not use the % inside an entry. (Outside it doesn't matter as it is ignored along with all the rest).

The entry

@ARTICLE{auchunbekannt,
  title = {Beispielaufsatz},
  journal = {Zeitschrift},
  year = {2001},
  %volume = {7},
  pages = {1--35, 99--291},
  annotation = {lorem},
}

will compile just fine with Biber (you will not get a volume field in the output of course), but BibTeX will throw an error. So a safer way to exclude a field is to rename it:

 xxxvolume = {7},

Similarly,

@article{B,
    author  = {Uthor, A.}, % her full name is Anne Uthor
    journal = {Journal 1},
    title   = {Title},
    year    = {2015},
}

will compile fine with Biber, but will throw the error

You're missing a field name---line 6 of file biblio.bib
 :         author  = {Uthor, A.}, 
 :                                % her full name is Anne Uthor
I'm skipping whatever remains of this entry

with BibTeX.

On the other hand

@article{A,
    author = {Author, A.},
    journal = {Journal 1},
    title = {Title %1
            },
    year = {2014},
}

can work with BibTeX, but with biber you would get this in the bbl:

\field{title}{Title %1}

and this leads to a runaway argument.

If your aim is an annotated bibliography, you can also annotate an entry inside the entry in a field unknown to Biber/BibTeX, this leaves the option of – if need be – allowing an output in the document. biblatex even has an annotation field that is optionally shown by the reading style, all other standard styles ignore it, it is passed to the .bbl file, though. A new field such as myann will be completely ignored by Biber and BibTeX and thus can be filled with your comments as well.