From 0d4cf5e4d3329724d268ffeb6bf159a4f0ac7a10 Mon Sep 17 00:00:00 2001 From: Chad Pytel Date: Mon, 30 Sep 2024 13:56:30 -0400 Subject: [PATCH] Don't use foo, bar, and baz (#716) It is possible that the term foobar has a [questionable etymology](https://en.wikipedia.org/wiki/Foobar#History_and_etymology), but in addition, these don't mean anything an in our code, as well as our documentation, there is almost always a more meaningful example to use that will better convey intent to other developers, and yourself in the future. We already have a line in our guides to "Name variables, methods, and classes to reveal intent." However, throughout our open source projects we have used this placeholder variables in code and documentation when a more meaningful alternative would have been better. This adds the point that this guideline also applies to documentation, and gives the examples of `foo`, `bar`, and `baz`, to hopefully make it clear what the guideline is saying to not do. --- general/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/general/README.md b/general/README.md index bee6ac6f..5b4a046e 100644 --- a/general/README.md +++ b/general/README.md @@ -41,7 +41,7 @@ violations. - Prefer naming classes after domain concepts rather than patterns they implement (e.g. `Guest` vs `NullUser`, `CachedRequest` vs `RequestDecorator`). - Name the enumeration parameter the singular of the collection (`users.each { |user| greet(user) }`). -- Name variables, methods, and classes to reveal intent. +- Name variables, methods, and classes to reveal intent. This includes documentation and examples (e.g. don't use `foo`, `bar`, `baz` in examples). - Treat acronyms as words in names (`XmlHttpRequest` not `XMLHTTPRequest`), even if the acronym is the entire name (`class Html` not `class HTML`).