From afed854a228c7912efc00c24d63a26e2d6401bc2 Mon Sep 17 00:00:00 2001
From: James Adams <james.adams@stfc.ac.uk>
Date: Fri, 6 Sep 2024 10:10:54 +0100
Subject: [PATCH] coding_style: Document each's evilness

---
 _development/coding_style.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/_development/coding_style.md b/_development/coding_style.md
index f9eed215..7290955c 100644
--- a/_development/coding_style.md
+++ b/_development/coding_style.md
@@ -119,6 +119,31 @@ And the bad example:
  my $circle_area = $radio * 3.14159 * 3.141592;
 ```
 
+### Don't use each
+
+`each` is evil, and although it can be used correctly, should be avoided at all costs.
+
+The problem is that each sort-of remembers the last element it iterated over, this has all sorts of nasty side effects.
+
+Use `foreach` to iterate over `keys` instead.
+
+Bad example:
+
+```perl
+while (my ($k, $v) = each(%h)) {
+    ...
+}
+```
+
+Good example:
+
+```perl
+foreach my $k (keys %h) {
+    my $v = $h{$k};
+    ...
+}
+```
+
 ### Module header
 
 A Perl module **must** start with a line like: