File naming conventions

[a-ok]

Not sure if this has been brought up before (probably not because it's a bit mental) but do you have any specific file name conventions? I struggle between matching the file extension language (phpFile.php, jsFile.php, appWtf-dunno__v1.scss) and just OS naming (hyphen only). Am I overthinking this? Does the consistency matter?

I've noticed the ProcessWire filenames vary (sometimes even PascalCase) and wondered if there was a pattern I was missing?

[Jo J]

Was curious too. I searched and, yes, it was brought up before. Here. 

TLDR.

As mentioned there, it becomes more important when multiple programmers are (or will be--next guy after you) involved. Also mentioned, was the additional benefit of self-documentation when you follow a naming convention.

To answer your question, being all implementors of the PW architecture (and PHP), it probably makes sense for us to be consistent with it. (Compared to other frameworks PW made it easy for us.)

Still, I did another round of refactoring recently and felt happier after. None of my direct templates have echos. Reduced them to about 10. Since they mostly describe a type of page (model), it's a 1 word all-lowercase filename. I have a couple of controller classes that I camelCased with an .inc extension so the admin wont see it...and added an underscore so its listed on top. I guess we all have different reasons.

[dragan]

There are coding guidelines for the core, but not specifically for filenaming (apart from modules, maybe).

1 hour ago, Jo Justo said:

makes sense for us to be consistent

Yes.

[wbmnfktr]

My experience with this in the past:

The more I thought about naming conventions the less files I created - therefore didn't get anything done.

Cleaning up afterwards was sometimes a mess but at least I had something to clean up. 

If you are working in a team, talk about it and think about it together. If you work alone you will find your way somewhere in the future.

 

[dragan]

5 hours ago, wbmnfktr said:

Cleaning up afterwards was sometimes a mess

That's where a good IDE is a big help. Whenever you rename stuff (files or variables etc.) it cleans up for you and searches for usages everywhere in your project.

[a-ok]

32 minutes ago, dragan said:

That's where a good IDE is a big help. Whenever you rename stuff (files or variables etc.) it cleans up for you and searches for usages everywhere in your project.

Go on... I wonder if Atom does this...

[dragan]

10 minutes ago, a-ok said:

I wonder if Atom does this

No, because Atom is just a text-editor. An IDE is much more than that: https://en.wikipedia.org/wiki/Integrated_development_environment

Some infos about how refactoring is made really easy e.g. in PHPStorm:

https://www.jetbrains.com/help/phpstorm/refactoring-source-code.html

https://www.youtube.com/watch?v=78ILII27MeY

https://www.youtube.com/watch?v=6EMM7HSc_2E

 

[horst]

8 hours ago, wbmnfktr said:

The more I thought about naming conventions the less files I created - therefore didn't get anything done.

:-) 

[a-ok]

9 hours ago, wbmnfktr said:

The more I thought about naming conventions the less files I created - therefore didn't get anything done.

This answer. Perfect.

What about template and field names within PW? Thoughts?

[louisstephens]

5 minutes ago, a-ok said:

This answer. Perfect.

What about template and field names within PW? Thoughts?

I have been curious about this as well. I am currently working on a project which unfortunately has grown to over 50+ fields (at the moment). I always see people writing about re-using fields as much as possible, but for the life of me I just get confused. I guess I just get hung up, ex: fields for  modal settings (header_color, width,  iframe_src)  and then having a different template that also has the same fields (but in a different context). I end up duplicating fields (which I know is terrible) and then going down a bad rabbit hole. 

[Robin S]

1 hour ago, louisstephens said:

I always see people writing about re-using fields as much as possible, but for the life of me I just get confused.

This is why I think we need a field aliases feature. I have a working module that allows the use of field aliases anywhere in template files and in /site/ready.php and /site/init.php, but issues with the File Compiler need to be fixed before the module can be released.

[teppo]

14 hours ago, louisstephens said:

I have been curious about this as well. I am currently working on a project which unfortunately has grown to over 50+ fields (at the moment). I always see people writing about re-using fields as much as possible, but for the life of me I just get confused. I guess I just get hung up, ex: fields for  modal settings (header_color, width,  iframe_src)  and then having a different template that also has the same fields (but in a different context). I end up duplicating fields (which I know is terrible) and then going down a bad rabbit hole. 

I don't want to dismiss this issue, but I also think that people sometimes overthink the whole field naming thing a bit. When you're creating a new field ...

1. Decide if this field is something you can reuse elsewhere. Things like "images" or "summary" are obvious candidates, and then there are the likes of "color", "width", and "background_color" that are likely to fit into this category as well. If you can see further use for the field (or rather the data it represents), go with a generic name.
2. If the field is very specific to the use case (based on it's purpose, context, or settings / formatting rules etc.) don't try to get too creative with the "always reuse" idea. If it's a field that's specifically designed to hold google_analytics_id, just name it accordingly.

Reusing fields is the best practice, but reusing fields for something they're not meant to do (and/or where they'll make no sense at all) will just mess up your information architecture – not to mention the issues it'll cause once you realise that in a particular use case you actually need to tweak some field setting that cannot be changed in template context.

(Note: I'm aware that you can nowadays make a lot of stuff changeable in template context. In my experience it doesn't necessarily mean that they work as expected, and even then it can result in a whole new layer of complexity. Personally I try to avoid that.)

50+ fields is plenty, but especially if it's a moderately big project, in my opinion it's nothing to be worried about.

... oh, and one more thing: sometimes I see folks create loads of "duplicate" fields such as email_1, email_2, email_3, etc. That's one one easy place to optimise: use one of the repeatable fiield types, ProFields table, etc. Table is particularly great because it can handle large amounts of data in an efficient manner ?

[wbmnfktr]

After my post yesterday I realized that there is actually more I do. At first I thought I don't think that much about naming but then I looked into a recent project and found several patterns that seem to be part of my workflow for a while now but I never saw that as a naming convention to be honest. It's more my laziness. I hate searching around so I group templates and fields in some cases to make things easier for me - I guess.

Templates for data that will never result in a viewable URL/page get the prefix data, for example:

1. dataPerson
2. dataWebsite
3. dataProject
4. dataProduct

Then there are templates that result in real pages/URLs which get the prefix content, for example:

1. contentPage
2. contentPost
3. contentEvent
4. contentGallery

Then there are templates for pages that result in real pages/URLs but don't contain real content on their own which get the prefix list, for example:

1. listBlog
2. listMovies
3. listRecipes
4. listTeams

There are some more templates types but I'll skip them here as they are too much based on my workflow and projects - sometimes.

"Yeah... but what do you do if a data template needs to be changed and a page should become viewable?"
Well... I rename it, create or rename the .php file, do the things that are necessary to get the task done and I'm ready to go. While developing a project this can happen - but not that often actually. It's more often the case later on when the website owner decides to push more content into Google's index. As it is a client request I'm totally happy with it and can invoice my work.

 

In terms of field names I go the way @teppo already mentioned but with a little twist at the end.

I name the fields depending on their purpose. 

• headline
• subline
• summary
• excerpt
• intro
• bodycopy
• images
• heroImage
• heroVideo
• videoYoutube
• videoVimeo
• urlFacebook
• urlTwitter
• urlLinkedin
• nameFirst
• nameLast
• nameFull

You can see that I try to group fields by their name structure. Instead of firstName and lastName I reverse the order and these fields stay together in my list of fields. That makes life much easier in case I need to look up something or want to find out if there is already a field I can use.

 

But... is this really a naming convention? I don't think so.

 

[a-ok]

30 minutes ago, wbmnfktr said:

After my post yesterday I realized that there is actually more I do. At first I thought I don't think that much about naming but then I looked into a recent project and found several patterns that seem to be part of my workflow for a while now but I never saw that as a naming convention to be honest. It's more my laziness. I hate searching around so I group templates and fields in some cases to make things easier for me - I guess.

Templates for data that will never result in a viewable URL/page get the prefix data, for example:

1. dataPerson
2. dataWebsite
3. dataProject
4. dataProduct

Then there are templates that result in real pages/URLs which get the prefix content, for example:

1. contentPage
2. contentPost
3. contentEvent
4. contentGallery

Then there are templates for pages that result in real pages/URLs but don't contain real content on their own which get the prefix list, for example:

1. listBlog
2. listMovies
3. listRecipes
4. listTeams

There are some more templates types but I'll skip them here as they are too much based on my workflow and projects - sometimes.

"Yeah... but what do you do if a data template needs to be changed and a page should become viewable?"
Well... I rename it, create or rename the .php file, do the things that are necessary to get the task done and I'm ready to go. While developing a project this can happen - but not that often actually. It's more often the case later on when the website owner decides to push more content into Google's index. As it is a client request I'm totally happy with it and can invoice my work.

 

In terms of field names I go the way @teppo already mentioned but with a little twist at the end.

I name the fields depending on their purpose. 

• headline
• subline
• summary
• excerpt
• intro
• bodycopy
• images
• heroImage
• heroVideo
• videoYoutube
• videoVimeo
• urlFacebook
• urlTwitter
• urlLinkedin
• nameFirst
• nameLast
• nameFull

You can see that I try to group fields by their name structure. Instead of firstName and lastName I reverse the order and these fields stay together in my list of fields. That makes life much easier in case I need to look up something or want to find out if there is already a field I can use.

 

But... is this really a naming convention? I don't think so.

 

YES!

What about assets? symbol__arrow--next.svg? symbol-arrow-next.svg?

Edited August 30, 2019 by a-ok

[wbmnfktr]

42 minutes ago, a-ok said:

What about assets? symbol__arrow--next.svg? symbol-arrow-next.svg?

After a quick look into some projects I took more care about files:

• assets (/site/templates/assets)
  • brand
    • brand-company-logo.ext
    • brand-company-og-image.ext
    • favicon.ico (just a backup - the .ico always sits in the document root)
    • favicon.png
    • ...
  • fonts
    • plex
    • proxima
  • icons* (icons often end in my .css files - a ProCache option, therefore names don't matter here)
    • whatever-123123.svg
    • the-file-912321.svg
    • was-named-or-4572.svg
    • helps-me-to.svg
    • find-the-icon.svg
    • i-need.svg
  • vendor
    • jquery
      • jquery-3.x.x.js
    • slick
  • z (storing things I don't need anymore without deleting them - just in case)

 

* icons are in 99% of all cases just decoration elements so I use them very often as backgrounds and not as images. Every image that's not content on its own or part of the content will not end in an <img .../> tag. In case of gallery arrows I try to use text links/span-elements and re-style them with CSS. The icon itself will be in my CSS most of the time.

[a-ok]

Any thoughts about SASS/CSS variable names? My guess would be to follow CSS naming convention but then they look like class names rather than variables (but maybe that is also okay).

This hole is deep...

[wbmnfktr]

Never felt comfortable with CSS naming conventions like BEM... I tried a lot but never really used it from start to finish.

My variable and/or class names are a wild, weird and colorful mix of everything. ?

And I'm even guilty for things similar to this:

.yet--another--color--change--experiment--123 {...}

.the__client--asked__for--it {...}

It's like eating healthy. I know how it's done but... ?