Evergreen Perl Service Comment Analysis
 Share
The version of the browser you are using is no longer supported. Please upgrade to a supported browser.Dismiss

 
$
%
123
 
 
 
 
 
 
 
 
 
ABCDEFGHIJKLMNOPQRSTUVWXYZ
1
The purpose of this document is to provide a little insight into the current state of comments in our Perl services code, and to also give folks an opportunity to improve that state. Ideas for clarification and improvement are welcome!
2
3
Explanation of Project
4
Using a very rudimentary metric, we have attempted to count lines of code, documenting comments, and commented code. While there are many schools of thought regarding the positive and detrimental effects of too few or too many comments, our general assumption here is that a modest number of comments is beneficial, particularly when considering the nature of a large open source project worked on by many individuals. Based on our current practice and the practices of other major projects, we feel that "well-commented" code is generally at least 10-15% comments. Happily, much of our current codebase meets this standard; some does not.
5
In addition, we also feel that a basic header should be included in every file to help orient those who may be unfamiliar with it (which is all of us from time to time). We recommend two simple things in each header: 1) "Synopsis:" - in ~10-100 words; 2) "First supported in:" - Evergreen version (or estimated version) when first supported, or "Incomplete/Unsupported". The goals here are to give users both an understanding of where they are and some basic context of how the service fits into the bigger picture and history of the project.
6
Finally, we believe it best for unused code to exist in a separate branch or in the file history, not perpetually as commented code. With this in mind, we are setting a goal to generally remove commented code, particularly if it is long-standing.
7
These recommendations may not be appropriate for every file, and the grading system may be wholly inaccurate for certain cases. If you feel a file should not be changed, please add a note to that effect in the sheet and declare as "DONE" (see below). This project is concerned with "basic" code comments only. POD-style comments (rare in our code) are not considered. Furthermore, consideration and expansion of our own API "desc" elements is highly recommended, but is also outside the limited scope of this project.
8
9
Instructions for Contributing
10
1) Pick one or more service files (listed in accompanying "Analysis" sheet) based on both familiarity with the contents and basic needs as represented in the grading.
11
2) Add your name/username to the appropriate column to claim that task (column will turn yellow).
12
3) Once finished, add the word "DONE" to the cell with your username (it will turn green).
13
(For an example, see the AA_Example.pm file at the top of the sheet.)
14
*) At any time, feel free to add explanatory notes to the "Notes" field in each row.
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
Loading...