search

nus-cs2103-AY2021S2 / forum

10 stars 0 forks source link

Are low level details in the DG a bug? #334

Closed JulietTeoh closed 3 years ago

JulietTeoh commented 3 years ago

I reported a bug in the DG stated that they had used low-level details when explaining how their feature was implemented. For instance, they stated the use of previousAppointmentLists.push(new ArrayList<>(appointments.asUnmodifiableObservableList())), which is a reference to actual code that I can see in their codebase.

I remember in tutorials that it was emphasised that the documentation should be sufficiently high-level as the reader can refer to the code for lower-level details.

However, they rejected my report saying that their explanation is "crystal clear" because "is the actual executing command to copy the appointments list and added to the previousAppointmentLists"

Is this a valid justification?

damithc commented 3 years ago

There is no rule against having code in the DG, but we have the following DG tip. image

So, it's a matter of deciding if the code snippet is even necessary to be in the DG. Some questions you can ask:

  1. What does that section of the DG is trying to explain to the reader?
  2. Is it even something the DG should be explaining (i.e., does it have value to a new developer trying to understand the design/implementation)?
  3. Is the code snippet essential to that explanation?
  4. Can the code snipped be shorter (or is pseudo-code a better choice)?
JulietTeoh commented 3 years ago

thank you prof!