Skip to content

Commit 97afab3

Browse files
AsnelChristianAsnelChristian
committed
Docs Update
1 parent 328236c commit 97afab3

File tree

16 files changed

+662
-18
lines changed

16 files changed

+662
-18
lines changed

‎README.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,30 @@ The aspect tree is given below:
7171
- `UnusedParameter <Root/Redundancy/UnusedVariable/UnusedParameter/README.rst>`_
7272

7373

74+
- `Smell <Root/Smell/README.rst>`_
75+
76+
77+
- `ClassSmell <Root/Smell/ClassSmell/README.rst>`_
78+
79+
80+
- `ClassLength <Root/Smell/ClassSmell/ClassLength/README.rst>`_
81+
82+
83+
- `DataClump <Root/Smell/ClassSmell/DataClump/README.rst>`_
84+
85+
86+
- `FeatureEnvy <Root/Smell/ClassSmell/FeatureEnvy/README.rst>`_
87+
88+
89+
- `Complexity <Root/Smell/Complexity/README.rst>`_
90+
91+
92+
- `MethodSmell <Root/Smell/MethodSmell/README.rst>`_
93+
94+
95+
- `Naming <Root/Smell/Naming/README.rst>`_
96+
97+
7498
- `Spelling <Root/Spelling/README.rst>`_
7599

76100

‎Root/Metadata/CommitMessage/Body/README.rst‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,32 @@ Subaspects
1515

1616
* `Existence <Existence/README.rst>`_
1717
* `Length <Length/README.rst>`_
18+
Example
19+
=======
20+
21+
.. code-block:: English
22+
23+
CI: Revert requests breakage workaround
24+
25+
# This is the commit message body
26+
27+
This reverts "CI: Workaround requests un-vendoring of chardet"
28+
commit 638bff9cd85bedb7e2e8c6184b41f547eca4f97c.
29+
30+
The broken bear VintBear has been disabled.
31+
32+
Related to https://github.com/coala/coala/issues/4277
33+
34+
35+
Importance
36+
==========
37+
38+
Sometimes the commit message shortlog do not give enough information
39+
on the code, in that case it is a good idea to have give some more
40+
information in the commit message body.
41+
42+
How to fix this
43+
==========
44+
45+
Enforce detailed, clear and meaningful commit messages' bodies.
46+

‎Root/Metadata/CommitMessage/README.rst‎

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,17 +8,34 @@
88

99
CommitMessage
1010
=============
11-
Your commit message is important documentation associated with your
12-
source code. It can help you to identify bugs (e.g. through
11+
Your commit message the documentation associated with your source code.
12+
13+
Subaspects
14+
==========
15+
16+
* `Body <Body/README.rst>`_
17+
* `Emptiness <Emptiness/README.rst>`_
18+
* `Shortlog <Shortlog/README.rst>`_
19+
Example
20+
=======
21+
22+
.. code-block:: English
23+
24+
YapfBear: Add `YapfBear`
25+
26+
27+
Importance
28+
==========
29+
30+
Good commit messages can help you to identify bugs (e.g. through
1331
`git bisect`) or find missing information about unknown source code
1432
(through `git blame`).
1533

1634
Commit messages are also sometimes used to generate - or write
1735
manually - release notes.
1836

19-
Subaspects
37+
How to fix this
2038
==========
2139

22-
* `Body <Body/README.rst>`_
23-
* `Emptiness <Emptiness/README.rst>`_
24-
* `Shortlog <Shortlog/README.rst>`_
40+
Enforce the use of commit messages.
41+

‎Root/Metadata/CommitMessage/Shortlog/README.rst‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,7 @@
88

99
Shortlog
1010
========
11-
Your commit shortlog is the first line of your commit message. It is
12-
the most crucial part and summarizes the change in the shortest possible
13-
manner.
11+
Your commit shortlog is the first line of your commit message.
1412

1513
Subaspects
1614
==========
@@ -20,3 +18,22 @@ Subaspects
2018
* `Length <Length/README.rst>`_
2119
* `Tense <Tense/README.rst>`_
2220
* `TrailingPeriod <TrailingPeriod/README.rst>`_
21+
Example
22+
=======
23+
24+
.. code-block:: English
25+
26+
FIX: Describe change further
27+
28+
29+
Importance
30+
==========
31+
32+
It is the most crucial part and summarizes the change in the shortest
33+
possible manner.
34+
35+
How to fix this
36+
==========
37+
38+
Enforce concise, meaningful and clear commit messages' shortlogs.
39+

‎Root/Metadata/README.rst‎

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
| ``Root.Metadata`` | `Parent <../README.rst>`_ | `Index <//github.com/coala/aspect-docs/blob/master/README.rst>`_ |
33
+-------------------+----------------------------+------------------------------------------------------------------+
44

5-
+---------------------+------------------------------------------+--------------------------------------+
6-
| **Sibling aspects** | `Redundancy <../Redundancy/README.rst>`_ | `Spelling <../Spelling/README.rst>`_ |
7-
+---------------------+------------------------------------------+--------------------------------------+
5+
+---------------------+------------------------------------------+--------------------------------+--------------------------------------+
6+
| **Sibling aspects** | `Redundancy <../Redundancy/README.rst>`_ | `Smell <../Smell/README.rst>`_ | `Spelling <../Spelling/README.rst>`_ |
7+
+---------------------+------------------------------------------+--------------------------------+--------------------------------------+
88

99
Metadata
1010
========
@@ -15,3 +15,24 @@ Subaspects
1515
==========
1616

1717
* `CommitMessage <CommitMessage/README.rst>`_
18+
Example
19+
=======
20+
21+
.. code-block:: all
22+
23+
Commit message, commit message shortlog, commit message body, etc...
24+
25+
26+
Importance
27+
==========
28+
29+
Writing good documentation on each changes we make on our code is
30+
always a good idea because it makes it easy to identify what went
31+
wrong, what change breaks things or introduce code smells etc...
32+
33+
How to fix this
34+
==========
35+
36+
Enforcing good committing convention to make things consistence, can
37+
be a fix for this.
38+

‎Root/Redundancy/README.rst‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
| ``Root.Redundancy`` | `Parent <../README.rst>`_ | `Index <//github.com/coala/aspect-docs/blob/master/README.rst>`_ |
33
+---------------------+----------------------------+------------------------------------------------------------------+
44

5-
+---------------------+--------------------------------------+--------------------------------------+
6-
| **Sibling aspects** | `Metadata <../Metadata/README.rst>`_ | `Spelling <../Spelling/README.rst>`_ |
7-
+---------------------+--------------------------------------+--------------------------------------+
5+
+---------------------+--------------------------------------+--------------------------------+--------------------------------------+
6+
| **Sibling aspects** | `Metadata <../Metadata/README.rst>`_ | `Smell <../Smell/README.rst>`_ | `Spelling <../Spelling/README.rst>`_ |
7+
+---------------------+--------------------------------------+--------------------------------+--------------------------------------+
88

99
Redundancy
1010
==========
@@ -17,6 +17,19 @@ Subaspects
1717
* `UnreachableCode <UnreachableCode/README.rst>`_
1818
* `UnusedImport <UnusedImport/README.rst>`_
1919
* `UnusedVariable <UnusedVariable/README.rst>`_
20+
Example
21+
=======
22+
23+
.. code-block:: C++
24+
25+
int foo(int iX)
26+
{
27+
int iY = iX*2;
28+
29+
return iX*2;
30+
}
31+
32+
2033
Importance
2134
==========
2235

‎Root/Redundancy/UnreachableCode/UnreachableStatement/README.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,12 @@ Example
3131
print (id(a))
3232
3333
34+
Importance
35+
==========
36+
37+
We should always keep our codebase clean, having dead code uselessly
38+
makes the code longer and ambiguous.
39+
3440
How to fix this
3541
==========
3642

‎Root/Smell/ClassSmell/ClassLength/README.rst‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
+---------------------------------------+----------------------------+------------------------------------------------------------------+
2+
| ``Root.Smell.ClassSmell.ClassLength`` | `Parent <../README.rst>`_ | `Index <//github.com/coala/aspect-docs/blob/master/README.rst>`_ |
3+
+---------------------------------------+----------------------------+------------------------------------------------------------------+
4+
5+
+---------------------+----------------------------------------+--------------------------------------------+
6+
| **Sibling aspects** | `DataClump <../DataClump/README.rst>`_ | `FeatureEnvy <../FeatureEnvy/README.rst>`_ |
7+
+---------------------+----------------------------------------+--------------------------------------------+
8+
9+
ClassLength
10+
===========
11+
This aspect checks on classes' definitions length in your codebase.
12+
13+
Tastes
14+
========
15+
16+
+---------------------+--------------------------------------------------------------+--------------------------------------------------------------+
17+
| Taste | Meaning | Values |
18+
+=====================+==============================================================+==============================================================+
19+
| | | |
20+
|``max_class_length`` | Represents the max number of lines for a class's definition. | **999** +
21+
| | | |
22+
+---------------------+--------------------------------------------------------------+--------------------------------------------------------------+
23+
| | | |
24+
|``min_class_length`` | Represents the min number of lines for a class's definition. | **1** +
25+
| | | |
26+
+---------------------+--------------------------------------------------------------+--------------------------------------------------------------+
27+
28+
29+
\* bold denotes default value
30+
31+
Subaspects
32+
==========
33+
34+
This aspect does not have any sub aspects.
35+
36+
Example
37+
=======
38+
39+
.. code-block:: Java
40+
41+
// This is large class given that the `max_class_length` is 20
42+
43+
public class Employee
44+
{
45+
private float salary;
46+
private float bonusPercentage;
47+
private EmployeeType employeeType;
48+
public Employee(float salary, float bonusPercentage,
49+
EmployeeType employeeType)
50+
{
51+
this.salary = salary;
52+
this.bonusPercentage = bonusPercentage;
53+
this.employeeType = employeeType;
54+
}
55+
public float CalculateSalary()
56+
{
57+
switch (employeeType)
58+
{
59+
case EmployeeType.Worker:
60+
return salary;
61+
case EmployeeType.Supervisor:
62+
return salary + (bonusPercentage * 0.5F);
63+
case EmployeeType.Manager:
64+
return salary + (bonusPercentage * 0.7F);
65+
}
66+
return 0.0F;
67+
}
68+
}
69+
70+
71+
Importance
72+
==========
73+
74+
Too large classes also known as God objects, result in ambiguous and
75+
difficult to debug source code; whereas too small classes (or lazy
76+
classes or freeloader) are sometimes useless.
77+
78+
How to fix this
79+
==========
80+
81+
Usually splitting up those classes into many other classes solves the
82+
problem.
83+

‎Root/Smell/ClassSmell/DataClump/README.rst‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
+-------------------------------------+----------------------------+------------------------------------------------------------------+
2+
| ``Root.Smell.ClassSmell.DataClump`` | `Parent <../README.rst>`_ | `Index <//github.com/coala/aspect-docs/blob/master/README.rst>`_ |
3+
+-------------------------------------+----------------------------+------------------------------------------------------------------+
4+
5+
+---------------------+--------------------------------------------+--------------------------------------------+
6+
| **Sibling aspects** | `ClassLength <../ClassLength/README.rst>`_ | `FeatureEnvy <../FeatureEnvy/README.rst>`_ |
7+
+---------------------+--------------------------------------------+--------------------------------------------+
8+
9+
DataClump
10+
=========
11+
This aspect detects `data clumps` in you codebase.
12+
13+
`Data clump` is a name given to any group of variables which are passed
14+
around together (in a clump) throughout various parts of the program.
15+
16+
Subaspects
17+
==========
18+
19+
This aspect does not have any sub aspects.
20+
21+
Example
22+
=======
23+
24+
.. code-block:: java
25+
26+
public static void main(String args[]) {
27+
28+
String firstName = args[0];
29+
String lastName = args[1];
30+
Integer age = new Integer(args[2]);
31+
String gender = args[3];
32+
String occupation = args[4];
33+
String city = args[5];
34+
35+
welcomeNew(firstName,lastName,age,gender,occupation,city);
36+
}
37+
38+
public static void welcomeNew(String firstName, String lastName,
39+
Integer age, String gender,
40+
String occupation, String city){
41+
42+
System.out.printf("Welcome %s %s, a %d-year-old %s " "from %s who works as a%s
43+
",firstName, lastName,
44+
age, gender, city, occupation);
45+
}
46+
47+
48+
49+
Importance
50+
==========
51+
52+
Data clumps make codes difficult to read, debug, scale, and also
53+
hardly reusable.
54+
55+
How to fix this
56+
==========
57+
58+
Formally group the different variables together into a single object.
59+

0 commit comments

Comments
 (0)