How do I document the code correctly?

[Hansvb]

Hi,
I am adding annotations to complex functions in my tool because I’m worried I’ll have partially forgotten what I meant by the time six months have passed. See the example. If I do this often, things will get very cluttered. Is there another way to document this, or is this approach common practice?

Code: Pascal  [Select][+][-]

1. {-------------------------------------------------------------------------------
2.   ZoomToLayer
3.   Adjusts the map camera so that the entire extent of the given layer becomes
4.   visible within the current viewport (the drawing area on screen).
5.  
6.   @param ALayer  The layer to zoom to. Its bounds are used to compute the
7.                  required scale and center position.
8.  
9.   The method:
10.     1. Retrieves the layer's bounding box (TEnvelope) in world coordinates.
11.     2. Gets the current camera (IMapCamera) and viewport (TViewport) from the map engine.
12.     3. Computes the scale needed so that the layer's width and height fit into
13.        the viewport with a 20% padding margin.
14.     4. Applies limits to the scale (clamping to avoid extreme values).
15.     5. Sets the camera's scale and centers it on the middle of the layer's bounds.
16.     6. Notifies the view (via prMapCameraChanged) that the camera has changed,
17.        triggering a redraw.
18.  
19.   Note: The viewport is the size of the drawing area in pixels (e.g., a TPaintBox
20.         on the form). The envelope is in world coordinates (e.g., meters for
21.         Web Mercator). The camera translates between these coordinate systems.
22. -------------------------------------------------------------------------------}
23. procedure TPresenterMain.ZoomToLayer(ALayer: IMapLayer);
24. var
25.   lEnv: TEnvelope;  // Bounding box of the layer (minX, minY, maxX, maxY) in world coordinates
26.   lCam: IMapCamera; // Camera object that defines where and how we look at the world
27.   lVp: TViewport;   // Size of the drawing area (the paintbox) in pixels
28.   lScaleX, lScaleY, lNewScale: Double; // Scale factors to fit layer into viewport
29. begin
30.   if ALayer = nil then Exit;
31.  
32.   // Get the layer's world extent (the minimal rectangle that encloses all its geometries)
33.   ALayer.GetBounds(lEnv);
34.   if (lEnv.Width <= 0) or (lEnv.Height <= 0) then
35.     Exit;
36.  
37.   // Fetch current camera and viewport from the map engine
38.   lCam:= fModel.GetMapEngine.GetCamera;
39.   lVp:= fModel.GetMapEngine.GetViewport;
40.  
41.   // Calculate the scale needed to fit the layer horizontally and vertically
42.   // We divide by 1.2 to add 20% padding so the layer is not cut off at the edges
43.   lScaleX:= (lVp.Width / lEnv.Width) / 1.2;
44.   lScaleY:= (lVp.Height / lEnv.Height) / 1.2;
45.  
46.   // Choose the smaller scale so both dimensions fit (aspect ratio is preserved)
47.   // Dus passend maken...(4)
48.   lNewScale:= lScaleX;
49.   if lScaleY < lNewScale then
50.     lNewScale:= lScaleY;
51.  
52.   // Clamp scale to sensible limits to avoid zooming too far in or out
53.   if lNewScale < 0.0001 then lNewScale:= 0.0001;
54.   if lNewScale > 5000 then lNewScale:= 5000;
55.  
56.   // Apply new scale and center the camera on the middle of the layer
57.   lCam.SetScale(lNewScale);
58.   lCam.SetCenterX((lEnv.minX + lEnv.maxX) / 2);
59.   lCam.SetCenterY((lEnv.minY + lEnv.maxY) / 2);
60.  
61.   // Notify the view that the camera has changed; the view will redraw the map
62.   fProvider.NotifyConsumers(prMapCameraChanged, nil, nil);
63. end;  

[MathMan]

@Hansvb

Don't know about "common practice" but I'm doing more or less the same - I like what you showed!

Myself I'm also noting things like alternatives I tried, but dismissed for a reason - I found I can't remember these after some time. And, if there are, caveats.

All in all - fine with me.

Cheers,
MathMan

[cdbc]

Hi Hans
I'd do this around your notes/comments:

Code: Pascal  [Select][+][-]

1. {%region 'ZoomToLayer' -fold}
2. {-------------------------------------------------------------------------------
3.   ZoomToLayer
4.   Adjusts the map camera so that the entire extent of the given layer becomes
5.   visible within the current viewport (the drawing area on screen).
6.  
7.   @param ALayer  The layer to zoom to. Its bounds are used to compute the
8.                  required scale and center position.
9.  
10.   The method:
11.     1. Retrieves the layer's bounding box (TEnvelope) in world coordinates.
12.     2. Gets the current camera (IMapCamera) and viewport (TViewport) from the map engine.
13.     3. Computes the scale needed so that the layer's width and height fit into
14.        the viewport with a 20% padding margin.
15.     4. Applies limits to the scale (clamping to avoid extreme values).
16.     5. Sets the camera's scale and centers it on the middle of the layer's bounds.
17.     6. Notifies the view (via prMapCameraChanged) that the camera has changed,
18.        triggering a redraw.
19.  
20.   Note: The viewport is the size of the drawing area in pixels (e.g., a TPaintBox
21.         on the form). The envelope is in world coordinates (e.g., meters for
22.         Web Mercator). The camera translates between these coordinate systems.
23. -------------------------------------------------------------------------------}
24. {%endregion}

The above is lazarus only, but FPC has got the equivalent:

Code: Pascal  [Select][+][-]

1. {$Region 'ZoomFromLayer' -fold}
2. {$EndRegion 'ZoomFromLayer'}

At least these ways you can fold/hide the comments into 1 line
Regards Benny

[Hansvb]

Hi Benny,

I have used region for functions that belong together. Then you collapse them all together. I didn't think about the fact that you can also do it per function. Furthermore, I think I'm going to keep a txt file next to it to put some more extensive notes. I can also keep it in Dutch then. Saves time searching for translation.

[eny]

The funny thing is that you now have documented things twice: you repeat the text from the method heading in the code.
Now you have double the maintenance
I actually follow your practice of documenting in the code the 'why' or the context, not the how, which can clearly be read from the code.

_{Ach, effe de tekst door Google translate en je hebt de NL versie} 

[Hobbit00]

I usually write documentation this way, at least for the most important objects.
For variables or class members and records, I limit myself to the "<summary>" entry and somtimes some "<remarks>"

This is a significant help in Delphi when writing code, as it produces a complete, speaking hint (see attachment) during use...
I normally use Delphi.

Code: Pascal  [Select][+][-]

1. /// <summary>
2. ///   Reads a text file and copies the contents between two markers into a byte array.
3. ///   If there are multiple blocks, they are all copied.
4. /// </summary>
5. /// <remarks>
6. ///   The file must be encoded in UTF8, the end of line must be the same as defined in current sLineBreak (platform dependent)
7. /// </remarks>
8. /// <returns>
9. ///   Return: byte array on sucessfull, nil on failure
10. ///   See also <see cref="TBytes"/> or <see cref="Array of bytes"/>.
11. /// </returns>
12. function ReadBytesBetweenMarkers(const AFileName: string; const StartMarker,
13.                                  EndMarker: string): TBytes;
14.  

[Lauriet]

There has been a number of books that talk about good coding/documentation. In essence 1 procedure 1 purpose, and well named procedures would minimize the comments/documentation needed.

e.g.
if something then
  do something.
needs documentation.

if ItsRaining then
  TakeUmbrella

needs no documentation.

Let the code explain itself.

[Hobbit00]

There has been a number of books that talk about good coding/documentation. In essence 1 procedure 1 purpose, and well named procedures would minimize the comments/documentation needed.
e.g.
if something then
  do something.
needs documentation.

if ItsRaining then
  TakeUmbrella
needs no documentation.

Let the code explain itself.

You are right, but for more complex things (like a function or class) is not enough a simple name. More verbose comments needed.
Look at my example. The function name explain itself, but more info is needed, which saves you the hassle of searching for the code and delving into it to understand what it does in particular, or of having to search for the relevant entry in the various help files available.