Как управлять особыми случаями и эвристикой

Мартин Фаулер сказал в своей книге по рефакторингу, что, когда вы чувствуете необходимость добавить комментарий к вашему коду, сначала посмотрите, можете ли вы инкапсулировать этот код в метод и дать этому методу имя, которое замените комментарий.

, чтобы в качестве аннотации вы могли создать метод с именем.

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;
}

Затем вы можете написать код вроде

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

Не жесткий и быстрый конкретный пример, но он поможет с удобочитаемостью через год или два.

Unit testing can help here. Having tests that actually simulate the special cases can often serve as documentation on why the code does what it does. This can often be better then just describing the issue in a comment.

Not that this replaces moving the special case handling to their own functions and decent comments...

I'm not usually an advocate of test driven development and similar styles that stress tests too much, but this seems to be a perfect case where a bunch of unit test can help a lot. And not even in the first place to catch bugs from later changes, but simply to document all the special cases that need to be addressed.

A few good unit test with comments in them are in itself the best description of the special cases. And the commenting of the code itself gets easier too. One can simply point to some unit tests that illustrate the problem that is being solved at that point in the code.

About the

I sometimes wish there was a way to embed or link graphics in the source code, so I could say effectively, "in the graph of this data set, this particular feature here was causing the routine to trigger incorrectly, so that's why this piece of code was added".

part:

If the "graphic" that you want to embed is a graph, and if you use Doxygen, you can embed dot commands 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.
*/

Дон Кнут изобрел грамотное программирование , чтобы упростить включение в документацию вашей программы графиков, графиков, диаграмм, математических уравнений и всего остального, что вам нужно для понимания. . Грамотная программа - отличный способ объяснить, почему что-то такое, как оно есть, и как это стало таким со временем. Существует множество инструментов для грамотного программирования; Инструмент "noweb" - один из самых простых и входит в состав некоторых дистрибутивов Linux.

It sounds like you need more thorough documentation than just code comments. That way someone could look up the function in question in the documentation and be presented with an example picture that requires a special case.

Не зная конкретной природы вашей проблемы, нелегко дать ответ, но по моему собственному опыту, следует избегать обработки особых случаев в жестком коде. Разве вы не думали о реализации механизма правил или чего-то подобного для обработки особых случаев вне вашего основного алгоритма обработки?