How specific is the development of a design document?

Question

I am creating a project document for a security subsystem, which should be written in C ++. I have created a class diagram and sequence diagram for basic use cases. I also indicated common attributes, associations, and methods for each of the classes. But I have not yet finalized the definition of methods to the C ++ level. Since I am new to C ++, like another developer, I wonder if it makes sense to go further and point to this level. Thoughts?

edit: Wow - totally opposed, unanimous. For example, I thought that it was all about defining const vs. non-const, passing references, handling the default constructor and assignment, etc. I think it was very useful to talk about this to this level of detail. I definitely got a clearer idea of ​​how the system will work. Maybe if I just do a few methods, for example, before diving into the code?

Answer 1

Since you're a newbie, it probably makes sense not to deploy.

Reason: You are still learning the language and how best to structure. This means that you will make mistakes first and you will want to correct them without constantly updating the documentation.

Answer 2

I would say that this makes no sense, and that you have gone too far. If you are new to C ++, you cannot write a detailed project document for a C ++ project. I would recommend you try to implement what you already have in C ++, find out by inevitable errors (for example, public attributes), and then come back and review it.

Answer 3

I would not recommend going to this level, but again you have already passed wherever I went to the design specification. My personal feeling is that putting a lot of effort into developing a detailed design will be wasted, as you learn when developing code that your guesses about how the code works are wrong. I would stick to a high-level design and think about using TDD (test-based development) to keep development and implementation low.

Answer 4

It really depends on who the project document is aimed at. If this is for a boss who is not technical, then you are well versed in what you have.

If this is for you, then you are using a tool that will help you, so you decide. I create project-level project docs when I create a project, but it is at a high level, so I can figure out what the features of the various classes should be. I found that in different languages ​​the main functions of the class have little in common with the programming language in which we work. Some of the internal details and functions needed, of course, may vary depending on the chosen language, but these are implementation details that I don’t worry at the design stage.

This certainly helps me find out, for example, that the authorization class may have an authentication function that takes a User object as a parameter. I don't care, during design, that I might need the inner shell of the md5 function to accomplish a specific purpose. I learn about this when coding.

The purpose of the initial design is to organize organized so that you can make progress with clarity and foresight, and not break and repeat the same function 4 times, because you forgot some scenario due to lack of planning.

EDIT: I work a lot in PHP, and I actually use PhpDoc to execute some project documents, simply by writing a method signature without implementation, and then detailing what the method should do in the Comments method header. This helps anyone who uses my class in the future, because design is documentation. I can also change the documentation if I need to make some changes during encoding.

I work a lot in php4, so I can not use interfaces. In php5, I create an interface and then implement it elsewhere.

Answer 5

The best way to specify how the code should match each other in the code . The design document is for other things that are not easy to express in code. You should use it to describe the actual need that the program fills, how it interacts with users, what are the limitations regarding hardware and operating systems. Of course, describe the general architecture of your application in a project document, but, for example, the API should really be described in the code that the API provides.

Answer 6

You have already gone far enough with some of the documentation. Since you are still new to C ++, when you understand the language, you can change the structure of your program. Then you will have to make changes to the documentation. I would suggest that you have already gone too far with the documentation. No need to drill it anymore

Answer 7

Like everyone else, you walked past where you need to go with design. Do you have a good set of requirements for the simple true / false level from which you derived this project? You can design all day, but if you don't have requirements that just say what you are going to do, no matter how good your design is.