Lots of problems

[brandonLi8]

This issue is more a list of a lot of issues, and is meant more for @googlebleh.

Problems:

1. README.md is severely lacking. "Small collection of personal scripts / tools" doesn't tell me anything.

   Should contain at least:

   • Installation steps, contributing guidelines, and preferably a general overview of the different scripts.
   • Contributing guideline
   • Preferably a general overview of the functionality of the different scripts
2. Every script should have a doc string explaining the functionality with some examples. For instance:

   #!/bin/bash
   #====================================================================================================
   #
   # Visits each repository listed in a file and applies the same command to each.
   # If the specified file cannot be found, it will check for a matching file in perennial/bin/data.
   #
   # Examples:
   #
   # // print the working directory of all active repos:
   # for-each.sh active-repos pwd
   #
   # // checkout master for all repos:
   # for-each.sh active-repos git checkout master
   #
   # // you can also string multiple commands together by putting everything inside quotes:
   # for-each.sh active-sims "npm install && grunt update"
   #
   # Author: Sam Reid
   # Author: Chris Malley
   # Author: Jonathan Olson (from work in grunt-all.sh)
   #
   #====================================================================================================

3. What's the license? Consider MIT (https://en.wikipedia.org/wiki/MIT_License)
4. Consider a Code of Conduct. Things can get messy when you're open source.
5. Consider a Code Style guideline. Something similar to https://google.github.io/styleguide/shell.xml should do, but should be established.
6. Consider A linter. For shell, something https://github.com/koalaman/shellcheck looks good.
7. No evidence of code reviews. (See https://www.evoketechnologies.com/blog/code-review-checklist-perform-effective-code-reviews/)
8. No issue labels. See https://help.github.com/en/articles/applying-labels-to-issues-and-pull-requests.
9. No evidence of testing. How would one trust your work?

[googlebleh]

1, 2) Hence "personal" scripts and tools. I'd be happy to provide more info about anything if someone is interested, but otherwise this mostly serves as a place for me to easily access / store scripts that I commonly use and with which I am familiar. 3) Yeah, MIT sounds good to me too. 4, 5) No current plans to have multiple PR approvers, so atm the code style is my style : ) 6) This sounds like something to configure in your editor. What about this needs to be changed as far as the repository content goes? 7) I reviewed it with Milano 2 weeks ago. He was very critical and helped me improve the performance two-fold. 8) There are issue labels. As exemplified by the labels on this issue : ) 9) I don't write bugs. If you don't trust my work, don't use it!

[brandonLi8]

Going backwards because why not:

9) I don't write bugs. If you don't trust my work, don't use it!

When you put it like that, no one will use your code. Be gracious. Users shouldn't have to go out of there way to test your work.

8) There are issue labels. As exemplified by the labels on this issue : )

Well played.

7. reviewed it with Milano 2 weeks ago. He was very critical and helped me improve the performance two-fold.

There is no issue corresponding to the review, and therefore no evidence of a review. Why was the review done privately?

6. This sounds like something to configure in your editor. What about this needs to be changed as far as the repository content goes?

Editor is irrelevant in this scenario. The coding is what changes (and the code is in the repo). If you install a linter, your code in the repo is more consistent.

4, 5) No current plans to have multiple PR approvers, so atm the code style is my style : )

Fair enough. Just now that this dissuades people from contributing.

Hence "personal" scripts and tools. I'd be happy to provide more info about anything if someone is interested, but otherwise this mostly serves as a place for me to easily access / store scripts that I commonly use and with which I am familiar.

If it is truly personal, why do you have a repo for it. Public repos should be used for open source projects that are for multiple people.

[googlebleh]

Going in a random order because why not:

Users shouldn't have to go out of there way to test your work.

In this context, I believe in the practice "Trust, but verify." As with code written by anyone, it's never a good assumption that code works. Ken Thompson, one of the creators of both Unix and Golang, gave a speech when he received his Turing Award that echoed this sentiment.

If it is truly personal, why do you have a repo for it. Public repos should be used for open source projects that are for multiple people.

I've used my public repos for sharing code examples. Although the target user base is myself, I often link my repositories to others, demonstrating how I have solved specific problems in the past, advising them to learn from my solution, not necessarily install / copy it.

Public repositories can also be useful by providing an easy way to retrieve my own code when setting up a new work environment. For example, if I'm setting up a new computer / virtual machine, I can use the public repository to quickly and easily retrieve my configurations + utilities.

There is no issue corresponding to the review, and therefore no evidence of a review.

If all that you require is an issue corresponding to the review, let this comment on this issue serve as evidence of the review. This can be the issue corresponding to the review.

no one will use your code.

Is this a problem? It's a personal collection, so it'd fulfill its purpose if I were the only one to use it.

If you install a linter, your code in the repo is more consistent.

How do you know that a linter was not used? If the point of the linter is consistency of code, then this is better described by a Coding Style Guide rather than the default preferences of an arbitrary linter.

[brandonLi8]

Going in a even more random order because why not:

If all that you require is an issue corresponding to the review, let this comment on this issue serve as evidence of the review. This can be the issue corresponding to the review.

Bad idea. You shouldn't have to look several comments in a thread to find evidence of the review.

How do you know that a linter was not used? If the point of the linter is consistency of code, then this is better described by a Coding Style Guide rather than the default preferences of an arbitrary linter.

Linting can be configured (not just default preferences). For example, if you were using grunt eslint, you would have a Gruntfile that points to a specific configuration. The reason why this is better than a "Coding style guideline" is simple: automation. Computers are far superior to humans. Linting automates everything while a code style guideline is more or less a human (unless you have a code formatter, but they often don't catch the things that a linter can catch). Also, linting does more than a code style guideline would do.

But that doesn't mean a coding style guideline isn't needed. Having both is a good idea (another problem with this repo).

I've used my public repos for sharing code examples. Although the target user base is myself, I often link my repositories to others, demonstrating how I have solved specific problems in the past, advising them to learn from my solution, not necessarily install / copy it. Public repositories can also be useful by providing an easy way to retrieve my own code when setting up a new work environment. For example, if I'm setting up a new computer / virtual machine, I can use the public repository to quickly and easily retrieve my configurations + utilities.

To the second point: you can quickly use a private repository to quickly and easily retrieve you configurations + utilities also...

To the first point: code examples isn't really the best way to use a repo.

In this context, I believe in the practice "Trust, but verify." As with code written by anyone, it's never a good assumption that code works. Ken Thompson, one of the creators of both Unix and Golang, gave a speech when he received his Turing Award that echoed this sentiment.

I see no unit testing or any evidence of testing. It would be better if you had a script to test all your scripts. Maybe use something like oracle's wercker to test the 'buildability.' In general, you should do your best to make the consumers life easy.

Is this a problem? It's a personal collection, so it'd fulfill its purpose if I were the only one to use it.

Keep it private if its personal.