Tag Info

Hot answers tagged

9

Unless the BA is also an technical architect, they should concern themselves with the "what it does" not the "how it does it". As a result, the BA writes the requirements and the technical architect writes the solution, and the developer writes the code. Sometimes (or quite often) these roles are shared by someone, so a dev could also be the architect of ...


9

Before the rise of personal computing, the most significant use of cryptography was to keep war plans secret. Keep in mind that programmable computing as we know it essentially began with Turing's work breaking German codes in World War II, and the age of personal computing was beginning just as the Cold War was drawing to a close--not that anyone knew it ...


6

In my opinion, comments should explain anything that cannot be made self-evident by the actual code, and any detailed external documentation you need should be generated from those comments (presumably as part of your automated build/deployment system). Clarifying what a class or function should be used for, what problems it was created to solve, and where ...


5

I find it good practice to add a sentence or two to document the intended usage of the exception class. For example, the documentation of java.lang.ArrayIndexOutOfBoundesException states: Thrown to indicate that an array has been accessed with an illegal index. The index is either negative or greater than or equal to the size of the array. Such a ...


4

Functional specifications are typically presented as a document, but depending on your purposes, creating the specification in Word may not be the best choice. There are other options - word processors, spreadsheets, and requirements management tools (1, 2) are some common tools used to create and maintain functional specifications. Requirements management ...


3

No. If people cannot read the code and understand what the code is doing, that is a sign that your code is poorly designed, overly complex, or poorly named (or some combination thereof). Comments don't fix those problems - they only exacerbate them. Use comments to describe why code is doing weird things. More conventional documentation is better for ...


1

Could you clarify what you mean by integrate with the IDE? Do you want to see it in your IDE? If so, you could build it as help files--look for a help file compiler that fits your IDE, most will have something available. Word used to be pretty bad for large documents and I'm guessing from your post it hasn't changed much. Way back in the day we used ...


1

I would say documenting knowledge is much more prone to change (especially if you have an urge to document it) than documenting intent. So documenting intent is more effective if comparing the two. Here is what I mean: When you are talking about how something is done it has two downsides: 1) It is not clear how you are doing something and so you are ...


1

Comments should not explain how the code works. The code is there to explain how it works. If the implementation is changed, the comment becomes incorrect. Mostly the comments should explain What the purpose of the code is. This allows you to change the implementation over time without invalidating the comment. Changing the purpose of the code is ...



Only top voted, non community-wiki answers of a minimum length are eligible