Comments that come after the code they refer to. And boilerplate in comments that adds nothing to meaning. Example (not made up)
int count_;
// effects: The number of objects.
I would be interested to know if (a) other people have seen this style (b) anyone prefers it to the alternative. I think this originates in the C++ standard. In Working Draft, Standard for Progamming Language C++ from 2005-10-19, section 17.3, which lists the conventions used to describe the C++ library. It provides a list of attributes for functions. It includes Requires, Effects, Postconditions, Returns, Throws and Complexity. In the context of a library it makes sense to list a function prototype and then its characteristics. It makes no sense to me to do that in the code itself.
There is a style, unnamed as far as I know, in which all functions return a status code, and all calls to such APIs are placed inside an if
-statement. An example is socket API calls in UNIX. For example, if all api calls return -1 on failure you may see something like this for a sequence of API calls:
if(api1() != -1) {
if(api2() != -1) {
if(api3() != -1) {
// all three api calls were ok - do stuff...
} else {
// handle api3 error
}
} else {
// handle api2 error
}
} else {
// handle api1 error
}
It seems like many people are completely comfortable with this. But I do not like the way it pushes the error handling out of the picture, moving it away from the API call it refers to. When you combine this style with selectvely ignoring some of the errors and omitting the brackets on one or more of the conditions, or where some additional work has to be done before one or more of the API calls, you have a style where a maintainer has to check for correctness every time they deal with it. Though more verbose I prefer
if(api1() == -1) {
// error - escape somewhere, maybe return -1 to caller.
}
if(api2() == -1) {
// error - escape
}
if(api3() == -1) {
// error - escape
}
// All three calls succeeded - do stuff here.
To me the latter seems so transparent that I have no idea why anyone uses the former. Except maybe it makes the programming seem more exciting, as you arrive breathlessly inside all those conditional brackets ready to do the real work.