113 lines
3.8 KiB
Plaintext
Executable File
113 lines
3.8 KiB
Plaintext
Executable File
<sect1 id="s1-code-conventions">
|
|
<title>Code Presentation Conventions</title>
|
|
|
|
<para>In addition to the standard document conventions covered in <xref
|
|
linkend="s1-intro-conventions">, there are some additional conventions
|
|
related specifically to discussing source code:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><classname>classname</classname></term>
|
|
<listitem>
|
|
<para>This is the name of a class in an object-oriented
|
|
(<firstterm>OO</firstterm>) programming language. For example, the
|
|
class
|
|
<classname>com.arsdigita.categorization.CategoryTreeNode</classname>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><methodname>method name</methodname></term>
|
|
<listitem>
|
|
<para>This is the name of a method in an OO programming language,
|
|
e.g. the method <methodname>getBaseDataObjectType</methodname>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><function>function</function></term>
|
|
<listitem>
|
|
<para>The name of a function or subroutine, as in a programming
|
|
language. For example, the function
|
|
<function>SecurityLogger.warn()</function>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><varname>variable name</varname></term>
|
|
<listitem>
|
|
<para>The name of a variable. For example, the variable
|
|
<varname>BASE_DATA_OBJECT_TYPE</varname>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>option</option></term>
|
|
<listitem>
|
|
<para>An option for a software command or
|
|
<methodname>Method</methodname>. For example, a user has been granted
|
|
<option>read</option> privileges on an object.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><returnvalue>return value</returnvalue></term>
|
|
<listitem>
|
|
<para>The value returned by a function. For example, a method returns
|
|
<returnvalue>null</returnvalue>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><replaceable>replaceable</replaceable></term>
|
|
<listitem>
|
|
<para>Content that may, must or will be replaced by the user or a
|
|
program. For example, the code is commented with
|
|
<computeroutput>NOTE(<replaceable>n</replaceable>)</computeroutput>,
|
|
where <replaceable>n</replaceable> is the number of the
|
|
<computeroutput>NOTE</computeroutput>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>program listing</term>
|
|
<listitem>
|
|
<para>A literal listing of all or part of a program. The
|
|
<computeroutput>\</computeroutput> character is used to break a line
|
|
for printing purposes. You will want to reconnect them back into a
|
|
single line, preserving the spacing in the line.
|
|
</para>
|
|
|
|
<programlisting>
|
|
import com.arsdigita.kernel.permissions.PermissionService;
|
|
import com.arsdigita.kernel.permissions.PermissionDescriptor;
|
|
import com.arsdigita.kernel.permissions.PrivilegeDescriptor;
|
|
import com.arsdigita.persistence.OID;
|
|
|
|
OID acsObject = new OID("example.MyACSObject",
|
|
new BigDecimal(50));
|
|
|
|
OID party = new OID("com.arsdigita.kernel.Group", new BigDecimal(5));
|
|
|
|
|
|
PermissionDescriptor perm =
|
|
new PermissionDescriptor(PrivilegeDescriptor.READ,
|
|
acsObject, party);
|
|
|
|
PermissionService.grantPermission(perm);
|
|
</programlisting>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>first term</term>
|
|
<listitem>
|
|
<para>The first occurrence of a term, such as the first time we
|
|
introduce a <firstterm>bulletin-board</firstterm> and note its
|
|
abbreviated form, <firstterm>bboard</firstterm>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect1>
|