Document naming conventions

Author: tisonkun

doc/Language/variables.pod6

@@ -1087,8 +1087,9 @@ X<|$?PACKAGE>X<|$?MODULE>X<|$?CLASS>X<|$?ROLE>X<|$?GRAMMAR>X<|$?TABSTOP>X<|$?ENC
 
 X<|$*ARGFILES>X<|@*ARGS>X<|$*IN>X<|$*OUT>X<|$*ERR>X<|%*ENV>X<|$*REPO>X<|$*TZ>
 X<|$*CWD>X<|$*KERNEL>X<|$*DISTRO>X<|$*VM>X<|$*PERL>X<|$*PID>X<|$*PROGRAM-NAME>
-X<|$*PROGRAM>X<|$*EXECUTABLE>X<|$*EXECUTABLE-NAME>X<|$*USER>X<|$*GROUP>X<|$*HOME>
-X<|$*SPEC>X<|$*TMPDIR>X<|$*THREAD>X<|$*SCHEDULER>X<|$*USAGE>
+X<|$*PROGRAM>X<|$*EXECUTABLE>X<|$*EXECUTABLE-NAME>X<|$*USER>X<|$*GROUP>
+X<|$*HOME>X<|$*SPEC>X<|$*TMPDIR>X<|$*THREAD>X<|$*SCHEDULER>X<|$*USAGE>
+
 =begin table
     $*ARGFILES        | An L<IO::ArgFiles> (an empty subclass of L<IO::CatHandle>)
                       | that uses C<@*ARGS> as source files, if
@@ -1168,7 +1169,7 @@ X<|$*SPEC>X<|$*TMPDIR>X<|$*THREAD>X<|$*SCHEDULER>X<|$*USAGE>
     $*SPEC            | The appropriate L<IO::Spec> sub-class for the platform that
                       | the program is running on.
     ------------------+--------------------------------------------
-    $*TMPDIR          | An L<IO::Path> object representing the "system temporary directory" as determined by L«C<.tmpdir IO::Spec::* method|/routine/tmpdir»
+    $*TMPDIR          | An L<IO::Path> object representing the "system temporary directory" as determined by L«C<.tmpdir IO::Spec::* method|/routine/tmpdir>»
     ------------------+--------------------------------------------
     $*TOLERANCE       | Used by the C<=~=> operator, and any operations that depend on it, to
                       | decide if two values are approximately equal. Defaults to 1e-15.
@@ -1195,6 +1196,24 @@ with the default changed before using C<.hyper> or C<.race>:
 
 This behavior is not tested in the spec tests and is subject to change.
 
+=head1 Naming Conventions
+
+It is helpful to know our naming conventions in order to understand what codes
+do directly. However, there is not yet a conventions list covering anywhere.
+Still we list several conventions that are widely held.
+
+=item1 Subs and methods from the built-ins library try to have single-word names when a good one could be found. In cases where there are two or more words making up a name, they are separated by a "-".
+
+=item1 Compounds are treated as a single word, thus C<substr>, C<subbuf>, and C<deepmap> (just like we write "starfish", not "star fish" in English).
+
+=item1 Subs and methods that are automatically called for you at special times are written in uppercase. This includes the C<MAIN> sub, the C<AT-POS> and related methods for implementing container types, along with C<BUILD> and C<DESTROY>.
+
+=item1 Type names are camel case, except for native types, which are lowercase. For the exception, you can remember it by: they are stored in a more compact way, so they names look smaller too.
+
+=item1 Built-in dynamic variables and compile-time variables are always uppercase, such like C<$*OUT>, C<$?FILE>.
+
+=item1 Methods from the MOP and other internals use "_" to separate multiple words, suck like C<add_method>.
+
 =end pod
 
 # vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6