Formatting comments with fancy blocks of asterisks reduces the readability of the actual comment, and draws the attention away from the code. XML comments should be used to enable documentation to be generated from the source code. 


== Noncompliant Code Example

[source,text]
----
' * --------------------------------- *
' *     This is a fancy header        *
' *       I am so proud of it         *
' * This comment is noncompliant

' This comment is also noncompliant *
----


== Compliant Solution

[source,text]
----
' I'm okay; you're okay.
----

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

include::message.adoc[]

endif::env-github,rspecator-view[]
