Timeline for Documenting my abstract class/interface - what is important?
Current License: CC BY-SA 4.0
10 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Jun 20, 2022 at 11:27 | history | edited | Christophe | CC BY-SA 4.0 |
added 18 characters in body
|
| Jun 20, 2022 at 11:23 | answer | added | Christophe | timeline score: 1 | |
| Jun 19, 2022 at 16:06 | comment | added | Cwt | @BrianKarabinchak Just curious about the three method (modify, validate and sanitize) - are there also other usages of those methods in the Form class? If, so they always are called in this group of 3 and in that order? | |
| Jun 19, 2022 at 16:03 | answer | added | Cwt | timeline score: 1 | |
| Jun 16, 2022 at 20:22 | comment | added | Filip Milovanović | Sounds about right. You know how, sometimes, when you're confronted with unfamiliar code, you kind of stare at it, and you pretty much understand what each line is doing, but it's not immediately obvious what the function (or the class) as a whole is trying to achieve and why - until it suddenly clicks, maybe after you've checked the surrounding/calling code, and played with the running application a bit, etc? And you're like: Oooh, that's why! Well, put that in the documentation, don't get too caught up in details. Give your readers the gist first; they can figure out the details later. | |
| Jun 16, 2022 at 18:54 | answer | added | candied_orange | timeline score: 3 | |
| Jun 16, 2022 at 18:05 | comment | added | Brian Karabinchak |
BTW, that person could be future you (in two weeks, or 3 months, or...), when you've forgotten what that code even was. In all likelihood it will be me 6 months from now lo. I appreciate your comments. So perhaps breaking it down onto each of the main things it can do - create a record, update a record, delete a record, save a file (if there's a report associated with it), and getting email presets regarding the record (used to populate email screens). A breakdown on the functionality - and inside each of those, what the subclass is responsible for to make it work. That sound right?
|
|
| Jun 16, 2022 at 16:38 | comment | added | Filip Milovanović | Regarding the level of detail: imagine you're writing for someone who's on your team (so, a programmer who is familiar with the project), but hasn't really used your class before and doesn't really know much about it, or how to properly extend it. BTW, that person could be future you (in two weeks, or 3 months, or...), when you've forgotten what that code even was. | |
| Jun 16, 2022 at 16:35 | comment | added | Filip Milovanović | Basically, you write down everything you've just said (albeit in a slightly more organized way) as documentation text; UML isn't particularly helful in this specific case. Describe what the class is for (what it does in general terms, how it fits or what its role is in your system), describe how people can make use of your class, and then describe the methods that the other devs might be interested in. Have a section on extension points: document what methods can be overridden, what are their inputs, outputs, mention any important non-obvious preconditions/postconditions that need to be met. | |
| Jun 16, 2022 at 15:20 | history | asked | Brian Karabinchak | CC BY-SA 4.0 |