How to manage special cases and heuristics

Question

I often have code based on a specific, well-defined algorithm. It is well commented and seems correct. For most datasets, the algorithm works fine.

But then rib cases, special cases, heuristics are added to solve specific problems with specific data sets. As the number of special cases grows, comments become more and more hazy. I am afraid to come back and look at this code after a year or so and try to remember why every special case or heuristic was added.

I’m sometimes sorry that there is a way to insert or link graphics in the source code, so I could say that "on the graph of this dataset this feature caused an incorrect procedure here, so why this code fragment was added."

What are some best practices for handling such situations?

Special cases are always required to handle these unusual / edge cases. How can it be controlled so that the code is relatively readable and understandable?

Let's look at an example related to recognizing functions with photos (not quite what I'm working on, but the analogy seems to be appropriate). When I find a specific picture for which the general algorithm does not work, and I need a special case, I record this information as best as possible in a comment (or as someone suggested below, a descriptive name for the function). But what is often missing is a permanent link to a specific data file that demonstrates the behavior in question. Although my comment should describe the problem and probably say “see the file foo.jp for an example of this behavior,” this file is never in the source tree and could easily get lost.

In such cases, do people add data files to the source tree for reference?

Answer 1

If you have a knowledge base or a wiki for a project, you can add a schedule to it by contacting it in the method according to Matthew Fowler quot e and also in the message for fixing the source control to change the boundary event.

//See description at KB#2312 private object SolveXAndYEdgeCase(object param) { //modify param to solve for edge case return param; } Commit Message: Solution for X and Y edge case, see description at KB#2312 

This works more, but a way to document things more thoroughly than just test cases or comments. Although it can be argued that test cases should be sufficient for documentation, you may not need to, for example, store all data failures in it.

Remember that vague problems lead to vague solutions.

Answer 2

Marcus Fowler said in his refactoring book that when you feel the need to add a comment to your code, first see if you can encapsulate this code in the method and give the method a name that replaces the comment.

so as an abstraction you can create a method with a name.

 private bool ConditionXAndYHaveOccurred(object param) { // code to check for conditions x and y return result; } private object ApplySolutionForEdgeCaseWhenXAndYHappen(object param) { //modify param to solve for edge case return param; } 

Then you can write code like

 if(ConditionXAndYHaveOccurred(myObject)) { myObject = ApplySolutionForEdgeCaseWhenXAndYHappen(myObject); } 

Not a simple and quick concrete example, but it will help with readability in a year or two.

Answer 3

Unit testing can help here. Testing that truly mimics special cases can often serve as documentation of why code does what it does. This can often be better than simply describing the problem in a comment.

Not that this replaces the transfer of handling special cases to their own functions and worthy comments ...

Answer 4

I'm usually not a fan of test-based development and similar styles that are too stress-tested, but this is apparently the ideal case where a bunch of unit test can help a lot. And not even in the first place, in order to catch errors from later changes, but simply to document all special cases that need to be resolved.

A few good unit tests with comments in them are in themselves the best description of special cases. And commenting on the code itself becomes easier. You can simply point out some unit tests that illustrate the problem that is being solved at this point in the code.

Answer 5

ABOUT

Sometimes I would like to have a way to embed or link to graphics in the source code, so I could say effectively, "on the graphics of this dataset, this particular feature here led to the subroutine not working correctly, so why this part of the code was added. "

part:

If the “graphic” you want to embed is a graph, and if you use Doxygen , you can insert dot in your comment to generate a graph in the documentation:

 /** If we have a subgraph looking like this: \dot digraph g{ A->B; A->C; B->C; } \enddot the usual method does not work well and we use this heuristic instead. */ 

Answer 6

Don Knut invented literate programming to make it easier for your program documentation to include graphs, graphs, charts, mathematical equations, and everything else you need to understand. A competent program is a great way to explain why something is so, and how it happens over time. There are many, many literate programming tools; the noweb tool is one of the easiest and comes with some Linux distributions.

Answer 7

Not knowing the specifics of your problem, it is not easy to give an answer, but in my own experience, handling special cases on hard code should be avoided. Have you not thought about introducing a rule engine or something similar to handle special cases outside of your main processing algorithm?

Answer 8

It sounds like you need more complete documentation than just code comments. Thus, someone could find the corresponding function in the documentation and present an approximate drawing requiring a special case.