Skip to content

Commit

Permalink
Warns Against Pointer Use in Standards (tgstation#86720)
Browse files Browse the repository at this point in the history
## About The Pull Request

I think they cause more harm then they're worth, since most usecases
(signals) are already better served by existing patterns like passing
lists by ref.

I am to some extent opening this pr to spark maintainer discussion so we
can have an amount of agreement on the topic. I think of these like
operator overloads, if it were not a very visible "new thing" I would
not add it to the documentation. I want to keep these out of general
use.

See .md changes for a more detailed breakdown of my concerns.

@tgstation/commit-access would like your thoughts on this, both the
content and the style it's been a while since I've written something for
the style/standard guides.

---------

Co-authored-by: AMyriad <[email protected]>
  • Loading branch information
LemonInTheDark and AMyriad authored Sep 20, 2024
1 parent 534f544 commit ed174b6
Showing 1 changed file with 24 additions and 0 deletions.
24 changes: 24 additions & 0 deletions .github/guides/STANDARDS.md
Original file line number Diff line number Diff line change
Expand Up @@ -513,6 +513,30 @@ The following is a list of procs, and their safe replacements.
* Move away from something, taking turf density into account `walk_away()` -> `SSmove_manager.move_away()`
* Move to a random place nearby. NOT random walk `walk_rand()` -> `SSmove_manager.move_rand()` is random walk, `SSmove_manager.move_to_rand()` is walk to a random place

### Avoid pointer use

BYOND has a variable type called pointers, which allow you to reference a variable rather then its value. As an example of how this works:

```
var/pointed_at = "text"
var/value = pointed_at // copies the VALUE of pointed at
var/reference = &pointed_at // points at pointed_at itself
// so we can retain a reference even if pointed_at changes
pointed_at = "text AGAIN"
world << (*reference) // Deref to get the value, outputs "text AGAIN"
// or modify the var remotely
*reference = "text a THIRD TIME"
world << pointed_at // outputs "text a THIRD TIME"
```

The problem with this is twofold.
- First: if you use a pointer to reference a var on a datum, it is essentially as if you held an invisible reference to that datum. This risks hard deletes in very unclear ways that cannot be tested for.
- Second: People don't like, understand how pointers work? They mix them up with classical C pointers, when they're more like `std::shared_ptr`. This leads to code that just doesn't work properly, or is hard to follow without first getting your mind around it. It also risks hiding what code does in dumb ways because pointers don't have unique types.

For these reasons and with the hope of avoiding pointers entering general use, be very careful using them, if you use them at all.

### BYOND hellspawn

What follows is documentation of inconsistent or strange behavior found in our engine, BYOND.
Expand Down

0 comments on commit ed174b6

Please sign in to comment.