Add section on panic

Author: Kate Osborn

docs/developer/go-style-guide.md

@@ -22,8 +22,8 @@ recommendations tailored to the project's specific requirements and coding style
 
 ### Use the empty struct `struct{}` for sentinel values
 
-Empty structs as sentinels unambiguously signal an explicit lack of information. For example, use empty struct for
-sets and for signaling via channels that don't require a message.
+Empty structs as sentinels unambiguously signal an explicit lack of information. For example, use empty struct for sets
+and for signaling via channels that don't require a message.
 
 DO:
 
@@ -52,37 +52,37 @@ DO:
 
 ```go
 func longFunctionDefinition(
-    paramX int,
-    paramY string,
-    paramZ bool,
+paramX int,
+paramY string,
+paramZ bool,
 ) (string, error){}
 
 // and 
 
 s := myStruct{
-    field1: 1,
-    field2: 2,
-    field3: 3,
+field1: 1,
+field2: 2,
+field3: 3,
 }
 ```
 
 DO NOT:
 
 ```go
 func longFunctionDefinition(paramX int, paramY string,
-    paramZ bool,
+paramZ bool,
 ) (string, error){}
 
 // or 
 
 func longFunctionDefinition(
-    paramX int, paramY string,
-    paramZ bool,
+paramX int, paramY string,
+paramZ bool,
 ) (string, error){}
 
 // or 
 s := myStruct{field1: 1, field2: 2,
-    field3: 3}
+field3: 3}
 
 ```
 
@@ -92,12 +92,12 @@ Example:
 
 ```go
 cfg := foo.Config{
-    Site: "example.com",
-    Out: os.Stdout,
-    Dest: c.KeyPair{
-        Key: "style",
-        Value: "well formatted",
-    },
+Site: "example.com",
+Out: os.Stdout,
+Dest: c.KeyPair{
+Key: "style",
+Value: "well formatted",
+},
 }
 ```
 
@@ -176,7 +176,7 @@ DO NOT:
 
 ```go 
 func(int required, int optional) {
-  if optional {...} 
+if optional {...} 
 }
 ```
 
@@ -186,15 +186,15 @@ DO:
 type Option func (o *Object)
 
 func Optional(string optional) Option {
-  return func (o *Object) {
-    o.optional = optional
-  } 
+return func (o *Object) {
+o.optional = optional
+} 
 }
 
 func (int required, ...Options) {
-  for o := range Options {
-    o(self)
-  } 
+for o := range Options {
+o(self)
+} 
 }
 ```
 
@@ -217,22 +217,22 @@ DO NOT:
 
 ```go
 func badAtStuff(noData string) error {
-  if len(noData) == 0 {
-    fmt.Printf("Received no data")
-  }
+if len(noData) == 0 {
+fmt.Printf("Received no data")
+}
 
-  return errors.New("received no data")
+return errors.New("received no data")
 }
 ```
 
 DO
 
 ```go
 func badAtStuff(noData string) error {
-  if len(noData) == 0 {
-    return errors.New("received no data")
-  }
-  ...
+if len(noData) == 0 {
+return errors.New("received no data")
+}
+...
 }
 ```
 
@@ -249,25 +249,25 @@ Example:
 
 ```go
 func onError(err error) {
-    // got an asynchronous error 
+// got an asynchronous error 
 }
 
 func ReadAsync(r io.Reader, onError) {
-  err := r()
-  if err != nil {
-    onError(err)
-  } 
+err := r()
+if err != nil {
+onError(err)
+} 
 }
 
 go ReadAsync(reader, onError)
 
 // OR errs := make(chan error)
 
 func ReadAsync(r io.Reader, errs chan<- error) {
-  err := r()
-  if err != nil {
-    // put error on errs channel, but don't block forever.
-  }
+err := r()
+if err != nil {
+// put error on errs channel, but don't block forever.
+}
 }
 ```
 
@@ -281,36 +281,51 @@ Example:
 
 ```go
 func readFile(filename string) ([]byte, error) {
-  file, err := os.Open(filename)
-  if err != nil {
-    return nil, fmt.Errorf("failed to open file: %w", err)
-  }
-  defer file.Close()
-  
-  data, err := ioutil.ReadAll(file)
-  if err != nil {
-    return nil, fmt.Errorf("failed to read file: %w", err)
-  }
-  
-  return data, nil
+file, err := os.Open(filename)
+if err != nil {
+return nil, fmt.Errorf("failed to open file: %w", err)
+}
+defer file.Close()
+
+data, err := ioutil.ReadAll(file)
+if err != nil {
+return nil, fmt.Errorf("failed to read file: %w", err)
+}
+
+return data, nil
 }
 
 func processFile(filename string) error {
-  data, err := readFile(filename)
-  if err != nil {
-    return fmt.Errorf("failed to process file: %w", err)
-  }
-  // Process the file data here
-  return nil
+data, err := readFile(filename)
+if err != nil {
+return fmt.Errorf("failed to process file: %w", err)
+}
+// Process the file data here
+return nil
 }
 
 func main() {
-  filename := "example.txt"
-  err := processFile(filename)
-  if err != nil {
-    fmt.Printf("Error processing file: %v\n", err) // caller handles the error
-  }
+filename := "example.txt"
+err := processFile(filename)
+if err != nil {
+fmt.Printf("Error processing file: %v\n", err) // caller handles the error
 }
+}
+```
+
+### Use panics for unrecoverable errors or programming errors
+
+Panics should be used in the following cases:
+
+1. Unrecoverable errors. An unrecoverable error is when NKG cannot continue running or its behavior or internal state
+   cannot be guaranteed. One example of this is if an error occurs when adding the Kubernetes API types to the Scheme,
+   or if an error occurs when marking a CLI flag as required.
+2. Programming errors. A programming error is an error that is only possible if there was a programming mistake. For
+   example, if the wrong type is passed or a go template is passed an invalid value.
+
+When using panics, pass an error as the argument. For example:
+```go
+panic(fmt.Errorf("unknown event type %T", e))
 ```
 
 ## Logging
@@ -334,24 +349,24 @@ Below are some general guidelines to follow for writing concurrent code:
   reentrant, you _must_ document that in the comments. Make it clear and obvious.
 - **Don't leak goroutines**: Goroutines are not garbage collected by the runtime, so every goroutine you start must also
   be cleaned up. Here's a couple of related principles:
-  - "If a goroutine is responsible for creating a goroutine, it is also responsible for ensuring it can stop the
-    goroutine." -- [Concurrency in Go][cig]
-  - "Before you start a goroutine, always know when, and how, it will stop." -- [Concurrency Made Easy][cheney].
+    - "If a goroutine is responsible for creating a goroutine, it is also responsible for ensuring it can stop the
+      goroutine." -- [Concurrency in Go][cig]
+    - "Before you start a goroutine, always know when, and how, it will stop." -- [Concurrency Made Easy][cheney].
 - **Blocking operations within a goroutine must be preemptable**: This allows goroutines to be cancelled and prevents
   goroutine leaks.
 - **Leverage contexts**: Contexts allow you to enforce deadlines and send cancellation signals to multiple goroutines.
 - **Avoid buffered channels**:  Use unbuffered channels unless there is a very good reason for using a buffered channel.
   Unbuffered channels provide strong synchronization guarantees. Buffered channels are asynchronous and will not block
   unless the channel is full. Buffered channels can also be slower than unbuffered channels.
-- **Protect maps and slices**: Maps and slices cannot be accessed concurrently (when at least one goroutine is writing) without locking. Doing so can lead to
-  data races.
+- **Protect maps and slices**: Maps and slices cannot be accessed concurrently (when at least one goroutine is writing)
+  without locking. Doing so can lead to data races.
 - **Never copy sync types**: see [above section](#do-not-copy-sync-entities).
 - **Choose primitives or channels based on use case**: In general, the Go language writers tell us to prefer channels
   and communication for synchronization over primitives in the sync package such as mutexes and wait groups. "Do not
   communicate by sharing memory. Instead, share memory by communicating". However, in practice, there are some cases
   where sync primitives are the better choice. For example, you should use primitives if you are working with a
   performance-critical section, or protecting the internal state of a struct. However, you should use channels if you
-  are transferring ownership of data (e.g. producer/consumer) or trying to coordinate multiple pieces of logic. 
+  are transferring ownership of data (e.g. producer/consumer) or trying to coordinate multiple pieces of logic.
 - **When possible, write code that is implicitly concurrent-safe**: Code that is implicitly concurrent-safe can be
   safely accessed by multiple goroutines concurrently without any synchronization. For example, immutable data is
   implicitly concurrent-safe. Concurrent processes can operate on the data, but they can't modify it. Another example is
@@ -398,27 +413,27 @@ FAVOR:
 
 ```go
 type Object struct{
-    subobject SubObject
+subobject SubObject
 }
 
 func New() Object {
-  return Object{
-    subobject: SubObject{},
-  }
+return Object{
+subobject: SubObject{},
+}
 }
 ```
 
 DISFAVOR:
 
 ```go
 type Object struct{
-    subobject *SubObject
+subobject *SubObject
 }
 
 func New() *Object {
-  return &Object{
-    subobject: &SubObject{},
-  } 
+return &Object{
+subobject: &SubObject{},
+} 
 }
 ```
 
@@ -440,8 +455,8 @@ DO NOT:
 
 ```go
 func(s string) *string {
-  s := s + "more strings"
-  return &s // this will move to heap 
+s := s + "more strings"
+return &s // this will move to heap 
 }
 ```