What is the business logic that your code implements? Do you really know?

Do you keep separate (and complete) documentation of the business logic implemented in the code?

I often get support cases where I dig into the code to find what's going on, and deep down discover some obscure case statement or an increment of a date by + 1, for example. Then I try to figure out what's going on, explain it to the users, and make changes if needed.

Comments on the "why's" of this logic in the code are usually non-existant. And in some cases I don't add comments either because I barely understand the business logic behind it. It's briefly explained just enough to make me understand how to change the code, and then I forget about it, and the users forget about the logic in the system.

From stackoverflow

• I try to pull all business rules into a config file, to at least document why those setting are specific set to the values. You dont have to dig through the code to find where they are set.

  Build separate(or mark accordingly) unit tests to test the business logic.

• Frustrating isn't? It's the bane of working with legacy code. "What the hell does this code do?" and "If I change it, what will it break and where?"

  Comments can't be trusted. They compile whether they are right or wrong... Documentation is no better. The system changes, how often will the documents be updated to reflect the change. If the system is already production, then the answer is almost never.

  The best solution to this is unit tests. If you have another proven method, I am all ears.

  jandersson : Haha, yes it's frustrating! The problem is that most of this code is T-SQL Stored Procedures, and Im not sure that there's a good way to unit test those.

• The biggest challenge with separate documentation is to keep it in sync with the code. That's why some people prefer to write the documentation in the code itself and generating the documentation through things such as SandCastle.

  Chuck Conway : You've never worked a large project spanning multiple years and hundreds of developer... relying on documentation doesn't work.

• No, we don't document it separately. But we write code that reads like poetry. If we were to document anything it would rather be all the things that don't work, so it would really not be the stuff we are coding - the code is the solution that works.

• I wrote about that problem here: http://stackoverflow.com/questions/400382/how-does-a-good-developer-keep-from-creating-code-with-a-high-bus-hit-factor#400436

  I do tend to write an FS when I write software. Apart from having an FS to review with the customer before writing code, if there were no FS then QA wouldn't be able to develop test cases.

• We keep 99% of the business-logic in separate files where it is specified (in a homebrew specification language), not hardcoded, so it's really easy to do regression (and other) testing on it. The remaining 1% of logic is too "complex" to be efficiently represented this way, but this very complexity implies that it is commented really well.

  At least, that's the theory. We constantly strive to keep reality not too far from it. :-)

• I am a bit baffled. From the responses, sounds like most people do not maintain a sep business logic documentation. Coming exclusively from a consulting background, I have always been curious as to how private/product companies handle this, especially since there is no "business analyst" job at companies like Microsoft (for example).

  So, how then do developers definitively know what to build (especially when many developers are working on an app) - in other words, what the business users communicated about their needs/requirements and ensuring/verifying you got it right (in other words, that your unit tests themselves are correct)? Moreover, if the same developer writing the code also writes the tests (probably often the case), there could be a problem with test accuracy.

  Perhaps an ultra-lean or during-construction documentation technique works better for certain types of applications (e.g., internal product development) as opposed to others (e.g., companies contracted to build business solutions) especially where there may be more creative license/leeway to evolve or refactor what to build? Even so, there must be some pre-coding documentation - mockups, notes, models, etc...

  EDIT http://steve-yegge.blogspot.com/2008/08/business-requirements-are-bullshit.html Just read this on Steve Yegge's blog. Spam comments at end of this post, but the gist is that you can probaby get away with anything if you are working on your own creative product development project. But as more than one commenter pointed out, many projects are not in this realm. Adding risk to the mix are solution longevity, construction duration, developers, must-have specs, risk of wrong specs (e.g, releasing private data or allowing unprivileged functions), and business logic complexity. A combination of these factors will determine how much trouble or risk one may invite by not documenting before construction. The risk may well be low for many projects.

  On the why, I do think that not knowing the why can make development soul-less and dreary. Unless one is writing some low-level plumbing or helper pieces, knowing why can help make development work more exciting and connected.