640051 - Align naming of stack-utils.js and dom_utils.js

Status: RESOLVED FIXED

(Mozilla QA Graveyard :: Mozmill Tests, defect)

Description

[Geo Mealer [:geo] -- This account is inactive after 2015-07-07]

We now have stack-utils.js and dom_utils.js. I'd prefer to standardize on either dash or underscore.

stack-utils.js claims its own name is stack_utils.js, so I suspect that's what should get renamed. OTOH, if Mozilla has a clear standard for how to do multiword file names, we should do that.

Re: multiword names in general, I personally try to avoid them. 

If I have to go there I usually just run words together unless they're really unclear, but given a choice I'd standardize on dash. Underscore is often problematic because cursors and underlining (including linkification) obscure it. 

I also try to avoid "utils" in names since it's a null word. By definition, anything in the file is a utility for whatever subject the file covers.

I'd personally have gone with collector.js (or nodecollector.js) and stack.js.

Comment 1

[Henrik Skupin [:whimboo][⌚️UTC+2]]

The node collector requires changes so I wouldn't take this module into account for the refactoring round now. But you are right in the general terms. We should rename stack-utils.js into stack.js and put it into a sub folder at the same time. This module is will only be used by 1 or 2 other modules and shouldn't be exposed at the top level module folder.

Comment 2

[Henrik Skupin [:whimboo][⌚️UTC+2]]

Oh and re '-' vs. '_'. You can't have a dash in the variable name.

Comment 3

[Geo Mealer [:geo] -- This account is inactive after 2015-07-07]

Good point, re: _ in identifiers.

Re: stack.js, anything private shouldn't be jsdoc'd as public then. I wouldn't bother jsdocing it at all, but if you do, make it @private.

I don't know that otherwise we need to hide the file in a subdir. The docs should be the guide as to what tests can use, not the directory structure. If you feel strongly we can hide it, though.

Comment 4

[Henrik Skupin [:whimboo][⌚️UTC+2]]

For now don't change any doc specification for stack.js, because at the moment test will partly of to use it. We will re-check the stack module in the refactoring round of milestone 2.

Comment 5

[Geo Mealer [:geo] -- This account is inactive after 2015-07-07]

Yeah, I won't change anything in there. But generally, I'd follow that guideline. 

Seems like jsdoc does the right thing with _identifiers, as you found out, but other things we might need to explicitly mark @private if they're going to have jsdoc style comments. dom_utils is also throwing trash into the _global section, for example.

Comment 6

[Henrik Skupin [:whimboo][⌚️UTC+2]]

dom_utils needs an update in general. So I would cover that part later. What about naming both modules to stack.js and dom.js?

Comment 7

[Geo Mealer [:geo] -- This account is inactive after 2015-07-07]

Sure, sounds good.

Comment 8

[Geo Mealer [:geo] -- This account is inactive after 2015-07-07]

Fixed with patch in Bug 638967

Comment 9

[Henrik Skupin [:whimboo][⌚️UTC+2]]

A side note here. This change broke some of our existing module tests. Next time please run the tests to ensure we don't break anything. I will fix that shortly.

Comment 10

[Geo Mealer [:geo] -- This account is inactive after 2015-07-07]

Sorry about that. I thought I did run the tests, but I must have missed the modules/test one on this change. That's another reason to not have two separate test directories, so that I can just run tests once and know they passed. Let's discuss later.