<commit_before>= Web Code Style Guidelines for the Seattle project =

This guide explains how to format code for the Seattle project that implements functionality exposed to the web. This guide should be seen as '''complementary''' to the general [CodingStyle code style guidelines], so please read that document thoroughly before you continue with the content below. Please let Ivan know if you have suggestions on ways to improve this page.

----
[[TOC(inline)]]
----

This guide contains general rules of thumbs, as well as instructions on how to format specific types of web files used by Seattle. This guide is expected to evolve, and should not be considered complete.

[[BR]]
== Django applications ==
----

Django code is written in Python, and falls under the purview of Seattle CodingStyle guidelines. However, Django is complex enough to warrant a few special cases.

[[BR]]
== Django views ==
----

 Decorators must be explained. Always.::

  - Django makes use of decorators to simplify complex functions. Each use of a decorator must be explained in the {{{<Note>}}} section of the function's docstring. Example:

{{{
#!python
@login_required()
def donations(request,share_form=None):
    """
    <Purpose>
    ...

    <Note>
        This method requires the request to represent a valid logged
        in user. See the top-level comment about the @login_required()
        decorator to achieve this property.
    """
}}}

[[BR]]
== Django models ==
----

 It critical to thoroughly document each class member and function in model Classes::

  * Django model classes define the interface to the database. 

  * Models naturally '''document''' the database schema
  
  * Django uses models to automatically generates the database schema

 Formatting Django model classes::

  * In general, each class member will need at least a single commented line of explanation. Example:
{{{
#!python
# date this donation was added to the db, auto added to new instances saved
date_added = models.DateTimeField("Date host added", auto_now_add=True)
# date we last heard from this machine, this field will be updated
# ** every time the object is saved **
last_heard = models.DateTimeField("Last time machine responded", auto_now=True)
# status: "Initializing", etc
status = models.CharField("Node status", max_length=1024)
}}}

  * Each model class must define a {{{__unicode__()}}} method, which is used to generated a meaningful string representation of the model. This method is crucial for effective debugging. Example:
{{{
#!python
def __unicode__(self):
    return "%s:%s:%d"%(self.user.www_user.username, self.ip, self.port)
}}}


[[BR]]
== Django templates ==
----

Django templates define a view on data generated by the Django application. Templates are written in a mix of HTML and Django templating language. Because there is no well-defined interface between templates and Django applications. This interface must be explicitly defined and maintained in comments maintained in the template file. It is important to maintain these comments in the template file because the template may be instantiated from different points in Django code, and may be used by different Django applications.

 * All templates should include a header that defines all the variables expected by the template. Here is an example:
{{{
#!python
example goes here
}}}

[[BR]]<commit_msg>Revision 40 of WebCodingStyle<commit_after>= Web Code Style Guidelines for the Seattle project =

This guide explains how to format code for the Seattle project that implements functionality exposed to the web. This guide should be seen as '''complementary''' to the general [CodingStyle code style guidelines], so please read that document thoroughly before you continue with the content below. Please let Ivan know if you have suggestions on ways to improve this page.

----
[[TOC(inline)]]
----

This guide contains general rules of thumbs, as well as instructions on how to format specific types of web files used by Seattle. This guide is expected to evolve, and should not be considered complete.

[[BR]]
== Django applications ==
----

Django code is written in Python, and falls under the purview of Seattle CodingStyle guidelines. However, Django is complex enough to warrant a few special cases.

[[BR]]
== Django views ==
----

Views are python functions which take a web request and return a web response.  These responses can be anything from redirects to 404 errors.  All of the Clearinghouse web pages are defined in views.py as well as all of the Django variables they use.  All web pages must be defined in views.py and also mapped to a URL in the urls.py file.
  
 Decorators must be explained. Always.  A Decorator is the "@whatever" before a views.py function.::

  - Django makes use of decorators to simplify complex functions. Each use of a decorator must be explained in the {{{<Note>}}} section of the function's docstring. Example:

{{{
#!python
@login_required()
def donations(request,share_form=None):
    """
    <Purpose>
    ...

    <Note>
        This method requires the request to represent a valid logged
        in user. See the top-level comment about the @login_required()
        decorator to achieve this property.
    """
}}}

[[BR]]
== Django models ==
----

 It critical to thoroughly document each class member and function in model Classes::

  * Django model classes define the interface to the database. 

  * Models naturally '''document''' the database schema
  
  * Django uses models to automatically generates the database schema

 Formatting Django model classes::

  * In general, each class member will need at least a single commented line of explanation. Example:
{{{
#!python
# date this donation was added to the db, auto added to new instances saved
date_added = models.DateTimeField("Date host added", auto_now_add=True)
# date we last heard from this machine, this field will be updated
# ** every time the object is saved **
last_heard = models.DateTimeField("Last time machine responded", auto_now=True)
# status: "Initializing", etc
status = models.CharField("Node status", max_length=1024)
}}}

  * Each model class must define a {{{__unicode__()}}} method, which is used to generated a meaningful string representation of the model. This method is crucial for effective debugging. Example:
{{{
#!python
def __unicode__(self):
    return "%s:%s:%d"%(self.user.www_user.username, self.ip, self.port)
}}}


[[BR]]
== Django templates ==
----

Django templates define a view on data generated by the Django application. Templates are written in a mix of HTML and Django templating language. Because there is no well-defined interface between templates and Django applications. This interface must be explicitly defined and maintained in comments maintained in the template file. It is important to maintain these comments in the template file because the template may be instantiated from different points in Django code, and may be used by different Django applications.

 * a template tag looks like:
{{{ 
#!python
   {% if myvariable %}
     //do stuff
   {% endif %}
}}}
These are used for built in Django code such as if statements, comments, for loops etc.  These change based on Django version so be mindful.

 * a template variable looks like:
{{{
#!python
  {{ myvessels }}
}}}
These are defined in views.py specifically for each web page.

 * All templates should include a header that defines all the variables expected by the template.  Try to be as specific as possible. Here is an example:
{{{
#!python
{% comment %}
<Program>
  myvessels.html

<Author>
  Originally by?:
  <NAME> 2009

  Modified:
  <NAME> Aug 14 2012
  
<Purpose>
  Django template file for Seattle Clearinghouse's 'My Vessels' page.  The page 
  allows a logged in user to acquire, renew or remove vessels.

<extends>
  control/control_base.html

<Stylesheet>
  myvessels.css

<Scripts>
  myvessels.js

<Template Variables>
  username:
    The currently logged in user.
	
  my_vessels: 
    list of infodicts of the user's currently acquired vessels.
    .node_ip:  last known ip
    .node_port:  last known port
    .vessel_id:  vessel name
    .node_id:  identifier for the node that the vessel is on
    .handle:  node id + ":" + vessel name
    .is_active:  whether the node is active
    .expires_in_seconds: expiration time, in seconds, for the vessel

  num_vessels: 
    Length of my_vessels list.

  sh_vessels: 
    List of shared vessels that are used by other but which belong to this user.

  get_form:
    The form to acquire vessels.  See forms.py for more info.
    .num: number of acquireable vessels.
    .env: enviromental variables example WAN, LAN, NAT, Random

  action_summary: 
    Generic error message.
{% endcomment %}
}}}

[[BR]]
{'fraction_non_alphanumeric': 0.0761698736194922, 'fraction_numerical': 0.002618695206649209, 'mean_word_length': 3.948732394366197, 'pattern_counts': {'":': 1, '<': 18, '<?xml version=': 0, '>': 18, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2927457', 'n_tokens_mistral': 2321, 'n_tokens_neox': 2185, 'n_words': 1182}