(Sorry, last post had wrong From: address)
Wesley Johnston wrote, On 06.12.2013 20:23:
We briefly also talked about just having better names for messages or
including documentation with messages. We could for instance, include
the place of origin, or info about whether a message is a response in
the message name.
Yes, I did the same in my codebase.
Messages warrant special documentation for 2 reasons:
* They don't have a formal definition like function(foo, bar) plus JavaDoc,
but are interspersed in the codebase, including their parameter handling
* They are the inter-module communication, so they are not obvious
from the code file you look at, and they are also are important
for a high-level understanding of what happens in the app.
Because of that, I made a very formal documentation of each message, on
both ends (sender and receiver), with name, parameters and their types
and meaning, but also what the message means and when it happens (these
are 2 different things).
A live example from my code (in this case a search field):
/**
* Messages sent by this module:
* "search-started"
* Means: We start a search.
* When: the user entered a search term into the search field
* Implementation limitation: ...
* Parameter: object
* searchTerm {String} what the user searches for
* source {int-enum} which widget or circumstance started the
search
* 2 = Firefox search field
* 3 = URLbar "keyword" search
* 4 = new tab page, search text field
* "search-keypress"
* Means: search term changed, but user is still typing
* When: User entered a character or pressed another key in the
search field
* Parameter: @see "search-started"
*
* Messages reacted to by this module:
* "search-term"
* Means: we have some text that we want to put in the search field
* When: User double-clicked on a word in a page
* Parameter: @see "search-started"
*/
All in all, there aren't that many messages that we send and receive,
but those that we do are important and non-obvious, so this has been a
good use of time to document these meticulously. Esp. in light of new
developers coming in and misunderstanding the details.
Ben
_______________________________________________
mobile-firefox-dev mailing list
[email protected]
https://mail.mozilla.org/listinfo/mobile-firefox-dev
