The style of error and warning messages is a bit all over the place right now. We should standardize them and document what is required.
An arbitrary suggestion (I’m fine with anything, really):
Start with capital letter
No fullstop at the end
Thus we say “Weights must be non-negative”, and not “weights must be non-negative” or “Weights must be non-negative.”
It’s not a huge deal but I’m always frustrated about not knowing what style to use when writing messages.
If we write guidelines for errors/warnings, here’s another suggestion: Provide context when possible and make the message as specific as possible. Thus, we say “Weights must be non-negative” and not “Invalid weight vector”. The former states why it is invalid.
Perhaps we should have something like a style guide at some point, detailing how things should be written. Similar things should hold for the documentation I think. For example, it would be good to standardize vocabulary, for example, always using vertex and edge instead of node and link. It would also be good to have a consistent style in how documentation is phrased (e.g. not using “this function does x”). There are some nice pointers from Java documentation, see this style guide.
One other thing, perhaps we should also explicitly document which types of graphs are acceptable to a function, and whether it deals correctly with various graph types. I’m thinking of listing something like listing whether it is acceptable to have graphs that contains:
Sure, we can broaden the discussion to include the documentation too.
But regarding the error/warning message style, I would like to come to a quick decision. I don’t mind which style we go with, I just want to settle on a standard.
@tamas@Gabor Are you happy with what I suggested above (capitalized, no fullstop)? If there are no complaints, I’ll write it up in a wiki. Otherwise just make a counter-suggestion. I’ll go along with anything. I am asking the two of you because not all styles may go well with how each interface reports these messages at the moment (it’s not the same for all of them).
Absolutely! I think I suggested (or meant to suggest) something similar before. In the case of high-level interfaces, add weighted/unweighted to that too (in C it’s pretty obvious if a function takes weights).
Mathematica started doing this a few years ago, after many inquiries from users about what graphs are supported (it differs from function to function). If you open the Details section of the documentation of most graph functions, you will see something like:
BetweennessCentrality works with undirected graphs, directed graphs, multigraphs, and mixed graphs.
(Personally, I’d make the phrasing a bit more verbose/explicit.)
That is a good point. So, the proposal is modified to:
Sentence case.
Full stop mandatory at the end.
Multiple sentences allowed if necessary, but keep the message as concise as possible.
Be as specific as possible, provide useful context for the user who will read the message.
Some more comments:
I did face the need to write more than one sentence as recently as yesterday:
I ended up with a questionable ;:
IGRAPH_ERROR("The graph has cycles; topological sorting is only possible in acyclic graphs", IGRAPH_EINVAL);
However, the error handler would usually print not one, but two messages. One is the “reason” for the error, the other is the text associated with the error code. For example, currently there is this function:
void igraph_error_handler_printignore (const char *reason, const char *file,
int line, int igraph_errno) {
IGRAPH_FINALLY_FREE();
fprintf(stderr, "Error at %s:%i :%s, %s\n", file, line, reason,
igraph_strerror(igraph_errno));
}
This could then be modified to something similar to:
"Error at %s:%i : %s %s.\n", file, line, reason, errorstring
Of course, each application will have their own error handler, which will need to be adapted.
To clarify, originally I suggested no fullstop because most messages do not currently have it. But that can be gradually fixed up. If the final error is assembled cleverly, then it won’t look very bad either with or without fullstop, so it’s not a big issue. E.g., separate the reason from the error string with a “—” character. Or if you prefer, add any missing fullstops dynamically in the interface you maintain. For the Mathematica interface, either solution is easy enough to implement.
I’m okay with the current proposal (sentence case, full stop). Should a higher-level interface need to present an error message in a context where a full sentence is not okay, at least it can rely on the fact that there will be a full stop at the end of the error message so the interface can strip it before displaying it to the user.