30-seconds-of-code: Naming Convention or Naming Guide

[kingdavidmartins]

Hey All 😄👋

I honestly think this Project is in desperate need for a naming guide/convention. With the project goal being able to provide learners far and wide a peak into the inner workings of popular used code snippets. I believe it's appropriate for the snippets to be consistent so the time spent isn't focused on finding the exact snippet they are looking for.

Example ES^~JavaScript & Lodash & Underscore Follow a type of rules That help them with categorizing and naming their methods

• If the method input is a array. In regardless of the output it is categorized as an array method
  -- _.join(array, [separator=',']) or .join() | _.join(['a', 'b', 'c'], '~') -> 'a~b~c'
  -- _.fromPairs(pairs) | _.fromPairs([['a', 1], ['b', 2]]) -> { 'a': 1, 'b': 2 }

As you can see even though they both return 2 different things. An Object and a String. Since they both accept array as inputs. They are categorized as Array methods

The reason I bring this up is because after a few minutes going through the snippets I realized

1. That more than a couple things are categorized wrongly making finding the needed snippet more harder than it needs to be

Example:

Object from key-value pairs

Use Array.reduce() to create and combine key-value pairs.

const objectFromPairs = arr => arr.reduce((a, v) => (a[v[0]] = v[1], a), {});
// objectFromPairs([['a',1],['b',2]]) -> {a: 1, b: 2}

Is categorized as an Object method / snippet. Yet it takes an arr as input and strays from the standard way of doing things. Which might be weird for other users.

1. And that we need to establish of a better guide to naming functions or it will become the wild wild west of snippet names. Which will take away from the value proposition we are trying to convey to the users of the project

Some of these snippet/ method names are way too long

@Chalarangelo Thoughts?

[Chalarangelo]

I agree that naming conventions need to be established and we need to review all snippet names retroactively, as well as new snippets that are being added. The tagging system was put into place to help solve the issue, but we need to establish guidelines on what snippets fall under each category.

[kingdavidmartins]

@Chalarangelo Yea I agree, Although the tagging helps with snippets/methods. We also have to make sure the snippets that are tagged are tagged in the appropriate category. Yea as far as guidelines for naming I have a few ideas to date.

1. categorySnippetName.md

Note

• camelCase convention with snippet starting with category
  
  
  
  • Snippet name & Fn name follow the same convention and guidelines
  
  

2. category-snippet-name.md

Note

• kebab-case convention with snippet starting with category
  
  
  
  • Snippet name & Fn name follow the same convention and guidelines
  
  

[skatcat31]

I do think a naming convention is needed, however I think the category might not be needed as part of the method name, but more as part of the file name as category${serperator}title.md so that the method name in the md can be whatever makes more sense, and the file name could be used to infer grouping instead of a DB that would need constant upkeep. Now each file decides where it goes in categorization, and each method can be whatever makes sense.

[Chalarangelo]

@skatcat31 Adding the category in the filename will cause all sorts of problems, as contributors will have to figure out the best category for each snippet and we will have to constantly nag them about what goes where. I honestly prefer the tag database, as we can untag snippets that are incomplete or whose functionality and usefulness is debatable, so that they do not compile in the build process and we can then take the time to figure it out among ourselves.

This will also aid the testing process, when implemented, as we can just untag files that do not pass all test cases to figure out what to do with them. If we have the tag in filename, we will have to manually add an exception list to the builder for snippets that are not yet ready.

I also considered splitting the snippets into folders, but that would make things even worse. The best case scenario for categorization in my opinion is to open another issue, dedicated to discussion of categorization (or open a second channel on gitter just for naming and categorization), where we keep track of all snippets and figure out what needs to be done.

As it currently stands, I suggest the following:

• Open an issue where we list all existing snippets alphabetically and start figuring out which ones are complete and sealed (as in we are not gonna alter them any further as they work perfectly fine).
• Start renaming what needs to be renamed and tagging things after we discuss them (I tagged everything semi-arbitrarily yesterday), so we can agree what goes where.
• Keep track of snippets that are not yet complete, need modifications and should be categorized differently.

In general, I want new contributors to sit down for 20 minutes, find something they want implemented, format a short snippet appropriately and submit a PR. We can then review the code and description, debate the usefulness and put the final touches there, such as changing the name, categorizing and setting up the tests when the time comes. This keeps the barrier of entry low and allows us to maintain the project fairly consistently without forcing new contributors to figure out our whole procedure. What do you guys say?

@darrenscerri @elderhsouza @kingdavidmartins @atomiks @skatcat31 I want your opinions!

[skatcat31]

This begs a question though... Multiple categories for a function. Should such a thing be allowed?

[fejes713]

@skatcat31 It definitely could be. While going through all the functions I also realized that some of them can fit into multiple categories. It's personal preference though, each of us categorizes things differently in our head.

For example, I would put both Random integer in range and Random number in range into Math category since they are operating with numbers and use Math built-in object. However, I also think that should stay at utility also.

[Chalarangelo]

@skatcat31 Multiple categories are a soft no in my opinion. I think we should keep functions simple enough to apply to one main situation. Yes, there are exceptions, but overall it would be better to keep everything categorized under only one category, so we don't have to deal with 90% of our functions being array-specific, string-specific and utilities at the same time.

@fejes713 I arbitrarily put those under utilities, but they might be better as math.

[fejes713]

@Chalarangelo You're right. Then we just need to focus on what category is best for every function. The ones I mentioned are not the only ones that might need category change. However, there's a separate issue for that I think.

[Chalarangelo]

Yes, we need to list the debatable ones in #159 and start organizing everything as we should.

[Chalarangelo]

As far as naming is concerned, I think we should switch our model to name files based on the contained function and then improve our descriptions to include the what and how of each function, so that users can see what the snippet is supposed to achieve along with how it does so. As it currently stands, it's really difficult to figure out what a few of the snippets do. Do you guys agree?

[Chalarangelo]

I'm closing this, let's discuss under #206 where there's a new proposal abut naming. Move categorization concerns under #159 so we can discuss that further, too.

[lock[bot]]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for any follow-up tasks.