Which code is better:
// C++
void handle_message(...some input parameters..., bool& wasHandled)
void set_some_value(int newValue, int* oldValue = nullptr)
// C#
void handle_message(...some input parameters..., out bool wasHandled)
void set_some_value(int newValue, out int oldValue)
or
bool handle_message(...some input parameters...) ///< Returns -1 if message was handled
//(sorry, this documentation was broken a year ago and we're too busy to fix it)
int set_some_value(T newValue) // (well, it's obvious what this function returns, so I didn't write any documentation for it)
The first one doesn't have and need any documentation. It's a self-documenting code. Output value clearly says what it means, and it's really hard to make a change like this:
- void handle_message(Message msg, bool& wasHandled) {
- wasHandled = false;
- if (...) { wasHandled = true; ...
+ void handle_message(Message msg, int& wasHandled) {
+ wasHandled = -1;
+ if (...) { wasHandled = ...;
With return values such change could be done easily
/// Return true if message was handled
- bool handle_message(Message msg) {
+ int handle_message(Message msg) {
...
- return true;
+ return -1;
Most of compilers don't (and can't) check documentation written in comments. Programmers also tend to ignore comments while editing code.
So, again, the question is:
if subroutine has single output value, should it be a procedure with well-named self-documenting output parameter, or should it be a function which returns an unnamed value and have a comment describing it?
