CPP RFC-02 [CRITICAL DOCUMENT TEMPLATES]
-
Jason Henderson wrote: What standards would you like to use for your project? Not Hungarian Notation X| - Anders Money talks, but all mine ever says is "Goodbye!"
I hate it too. I alwas start my
ints with i's not n's. :)Jason Henderson
"The best argument against democracy is a five-minute conversation with the average voter." - Winston Churchill
-
I hate it too. I alwas start my
ints with i's not n's. :)Jason Henderson
"The best argument against democracy is a five-minute conversation with the average voter." - Winston Churchill
I have been working on project where some people used Hungarian Notation, and some did not. It was really not a big issue, because we accepted the others style, and everyone was happy because they could code using their own style... - Anders Money talks, but all mine ever says is "Goodbye!"
-
I have been working on project where some people used Hungarian Notation, and some did not. It was really not a big issue, because we accepted the others style, and everyone was happy because they could code using their own style... - Anders Money talks, but all mine ever says is "Goodbye!"
Telling your team how to write readable code is a good thing. You're not going to change the way a particular team member writes code in a general sense, but you can tell them what is acceptable and what isn't. int i; // bad int iCounter; // good int iCounterForJasonsWidgetClass; // too much That sort of thing.
Jason Henderson
"If you are going through hell, keep going." - Winston Churchill
-
Requested by: Jason Henderson All Request For Comments (RFC) should be posted on my message board[^] where I will then post them here at the proper time. BEGIN ================================================= We need templates or guidlines for writing some critical documents. 1) Design Document 2) guidelines for enhancement suggestions or initial ideas (may not be critical) 3) Project Timeline 4) QA checklists? First of all, do we need some of these? Which do you think are necessary and which aren't (and why)? Any others? Second, what needs to be in these documents? If you have some templates, please submit them for review... somehow. :~ ================================================= END
Jason Henderson
"The best argument against democracy is a five-minute conversation with the average voter." - Winston Churchill
The design document is more than just a few pages of design stuff. The "design document" lives in spirit and name only and is comprised of several parts as well as a coherent underlying arcetechture. The design document is best represented by the following components: 1. A system design document. 2. An interface control document. 3. A system-level requirements document. 4. A software-level requirements document. 5. A requirements testing and tracibility document. 6. A software process and quality control document. However, we need to take a few steps back before we can really go forward. We need to start at the preliminary design phase. This phase is the most informal phase of system design. This is where we start brainstorming over what the project entails and what it's final goals and visions are. We need to clearly discuss the need for our software, the problems and shortcomings it's going to solve, and how the customer will use it. We are really approaching the "sizing" phase. That is literally what it means, we begin to "size" the project and see how big or small everything really is. We then talk about the interface. How is the customer going to use our product? The interface is the most important aspect of the system because that's what the customer sees. ---ASIDE--- I use the term "customer" quite loosely. "Customer", as we need to define it here, is anyone who will be using our code, be it in terms of some final application, or as a functional library. We have both internal and external customers. Everyone on the team will be a supplier or a customer to another member of the team several times throughout the project lifecycle. ---/ASIDE--- ---ASIDE2--- I remember going through this stuff in my senior design class and it made no sense to me whatsoever. It wasn't until I was out in the proverbial "real world" that I saw all this stuff in action. So in this light, I will try to clearly explain the design process as we go. If anything is vague or ambiguous, don't hesitate to ask for clarification. ---/ASIDE2--- Anyway, for a preliminary outline for the system design document, I would break it up as follows:
I. Abstract
A. What problem or shortcoming is the system going to solve?
(here we state the case for the project and justify why we are doing it)B. How does the system solve that problem? (high-level here, not too much detail) C. How do you plan on implementing the system? (process, -
Telling your team how to write readable code is a good thing. You're not going to change the way a particular team member writes code in a general sense, but you can tell them what is acceptable and what isn't. int i; // bad int iCounter; // good int iCounterForJasonsWidgetClass; // too much That sort of thing.
Jason Henderson
"If you are going through hell, keep going." - Winston Churchill
What about
for (int i = 0; i < 10; i++)
{
//bla bla bla...
};P - Anders Money talks, but all mine ever says is "Goodbye!"
-
What about
for (int i = 0; i < 10; i++)
{
//bla bla bla...
};P - Anders Money talks, but all mine ever says is "Goodbye!"
there are exceptions :-O
Jason Henderson
"If you are going through hell, keep going." - Winston Churchill
-
Jason Henderson wrote: What standards would you like to use for your project? Not Hungarian Notation X| - Anders Money talks, but all mine ever says is "Goodbye!"
Anders Molin wrote: Not Hungarian Notation I am not a fan of hungarian notation, but it is useful when its limited in some ways: m_ for a member var s_ for a static member var m_bVariable for bools/flags I don't really care about the rest, as long as its descriptive so you can tell what a variable is for! Whats really more important is the encapsulation and const correctness of the code. Roger Allen Sonork 100.10016 Were you different as a kid? Did you ever say "Ooohhh, shiny red" even once? - Paul Watson 11-February-2003
-
Requested by: Jason Henderson All Request For Comments (RFC) should be posted on my message board[^] where I will then post them here at the proper time. BEGIN ================================================= We need templates or guidlines for writing some critical documents. 1) Design Document 2) guidelines for enhancement suggestions or initial ideas (may not be critical) 3) Project Timeline 4) QA checklists? First of all, do we need some of these? Which do you think are necessary and which aren't (and why)? Any others? Second, what needs to be in these documents? If you have some templates, please submit them for review... somehow. :~ ================================================= END
Jason Henderson
"The best argument against democracy is a five-minute conversation with the average voter." - Winston Churchill
The Design Document template that I usually use with my clients (a rough sketch of it, and not all pieces apply all the time):
1. General Information
a. What is the problem?
b. What is the proposed solution?
c. What is the cost benefit of the solution?-
Current Practices/Procedures
a. How is this problem being solved currently?
b. Who is involved in the current process?
c. What are their responsibilities?
d. What processes/knowledge is "hidden", and by whom? -
Changes To Practices/Procedures
a. What changes are proposed?
b. Who are the people affected?
c. How are their responsibilities changed?
d. What training/documentation support will be required?
e. Who maintains the new implementation? -
Technologies
a. What existing technologies will be used?
b. What new technologies need to be developed?
c. Cost/Stability/Maintainability/Documentation of all technologies -
Design Overview
a. High level concepts/components/modules/functions
b. Identification of concerns: high level interactions
c. Identification of interests: who needs to know what from whom? (not people but concepts)
d. Early identification of trouble spots
e. Prototypes required
f. Planned QA / Test bed processes
g. Instrumentation/Profiling plans
h. Documentation plans
i. Error management (hardware, third party, internal) -
Detail Design
a. Flowcharts
b. State diagrams
c. Design Patterns--how will separation of concerns be implemented?
d. Data Management- data lifetime
- data persistence
- data transfer between components
e. User Interface Prototype
f. Database Schema Prototype
g. Error handling/recovery
h. Psuedo-code
-
Design Iteration
a. Identify areas of risk, requiring design review/changes
b. Identify areas of lack of information, requiring further design depth
c. Identify areas of innovation, suggesting risk, buy in problems, or maintenance problems
Marc Help! I'm an AI running around in someone's f*cked up universe simulator.
Sensitivity and ethnic diversity means celebrating difference, not hiding from it. - Christian Graus
Every line of code is a liability - Taka Muraoka
Microsoft deliberately adds arbitrary layers of complexity to make it difficult to deliver Windows features on non-Windows platforms--Microsoft's "Halloween files" -
-
Requested by: Jason Henderson All Request For Comments (RFC) should be posted on my message board[^] where I will then post them here at the proper time. BEGIN ================================================= We need templates or guidlines for writing some critical documents. 1) Design Document 2) guidelines for enhancement suggestions or initial ideas (may not be critical) 3) Project Timeline 4) QA checklists? First of all, do we need some of these? Which do you think are necessary and which aren't (and why)? Any others? Second, what needs to be in these documents? If you have some templates, please submit them for review... somehow. :~ ================================================= END
Jason Henderson
"The best argument against democracy is a five-minute conversation with the average voter." - Winston Churchill
A general comment on a project timeline. I think the project should be more functional driven, based on the vagueries of people's ability to work on things, and possibly that people might come and leave a project during it's development. I think the project leads should have a very clearly defined functional milestone schedule. I have my doubts that a time-based schedule is necessary, enforcable, or useful. Marc Help! I'm an AI running around in someone's f*cked up universe simulator.
Sensitivity and ethnic diversity means celebrating difference, not hiding from it. - Christian Graus
Every line of code is a liability - Taka Muraoka
Microsoft deliberately adds arbitrary layers of complexity to make it difficult to deliver Windows features on non-Windows platforms--Microsoft's "Halloween files" -
A general comment on a project timeline. I think the project should be more functional driven, based on the vagueries of people's ability to work on things, and possibly that people might come and leave a project during it's development. I think the project leads should have a very clearly defined functional milestone schedule. I have my doubts that a time-based schedule is necessary, enforcable, or useful. Marc Help! I'm an AI running around in someone's f*cked up universe simulator.
Sensitivity and ethnic diversity means celebrating difference, not hiding from it. - Christian Graus
Every line of code is a liability - Taka Muraoka
Microsoft deliberately adds arbitrary layers of complexity to make it difficult to deliver Windows features on non-Windows platforms--Microsoft's "Halloween files"It would be nice for people to be able to see when you think things will be finished. If that can be accomplished in a milestone schedule, then thats fine. As far as standard documents for projects, I would like to see some semblance of a timeline or a "time to reach goals" chart, or a projected milestones chart.
Jason Henderson
"If you are going through hell, keep going." - Winston Churchill