# Better documentation for properties vs. fields

**URL:** <https://discourse.julialang.org/t/better-documentation-for-properties-vs-fields/68173>\
**Category:** Internals & Design\
**Tags:** documentation\
**Created:** [September 14, 2021, 8:56pm UTC](https://discourse.julialang.org/t/better-documentation-for-properties-vs-fields/68173 "2021-09-14T20:56:12Z")\
**Posts on this page:** 8\
**Page:** 1

<div class="post-metadata">

**Author:** ![nandoconde](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/nandoconde/32/19497_2.png) [@nandoconde](https://discourse.julialang.org/u/nandoconde)\
**Post date:** [September 14, 2021, 8:56pm UTC](https://discourse.julialang.org/t/better-documentation-for-properties-vs-fields/68173/1 "2021-09-14T20:56:12Z")

</div>

# Background

I found myself often using the quite uncomfortable

```julia
fieldnames(typeof(x))

```

Searching for something unrelated, I found in an old thread this magic:

```julia
propertynames(x)

```

Which turns out to be a fantastic alternative without so much boilerplate, and also the recommended way to override `fieldnames` functionality for those situations in which you want to keep attributes private, etc. The thing is, **this is poorly documented**.

# How well documented are both alternatives

A quick search in the docs shows that [`fieldnames`](https://docs.julialang.org/en/v1/search/?q=fieldnames):

- is referenced more times across the docs (8 times)
- is referenced within “more important sources”, i.e., [Essentials](https://docs.julialang.org/en/v1/base/base/) and [Types](https://docs.julialang.org/en/v1/manual/types/) pages
- is referenced twice within devdocs, [Reflection](https://docs.julialang.org/en/v1/devdocs/reflection/) and [ASTs](https://docs.julialang.org/en/v1/devdocs/ast/)

Whereas [`propertynames`](https://docs.julialang.org/en/v1/search/?q=propertynames):

- is less referenced (only 4 times)
- only shows up in one “important” page, [Essentials](https://docs.julialang.org/en/v1/base/base/), which is the least self-explanatory source of information, because it is just a collection of Base

# Final discussion

However, there is a more important point to make here, further than achieving more coverage for `propertynames` (quote for emphasis):

> **Properly documenting the distinction between _properties_ and _fields_.**

Several programming patterns depend upon exposing some fields of an struct and hiding others, or discouraging direct access to struct fields and rather use “getters”/“setters” (or any _ad hoc_ method). This is the nature of the difference between fields and properties, and should be explained somewhere.

# Final question

Can I propose a PR? Will it be welcome? Is this just me?

---

<div class="post-metadata">

**Author:** ![JeffreySarnoff](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jeffreysarnoff/32/1980_2.png) [@JeffreySarnoff](https://discourse.julialang.org/u/JeffreySarnoff)\
**Post date:** [September 14, 2021, 9:22pm UTC](https://discourse.julialang.org/t/better-documentation-for-properties-vs-fields/68173/2 "2021-09-14T21:22:03Z")

</div>

you can  
you may  
you should

---

<div class="post-metadata">

**Author:** ![simeonschaub](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/simeonschaub/32/216566_2.png) [@simeonschaub](https://discourse.julialang.org/u/simeonschaub)\
**Post date:** [September 15, 2021, 1:48am UTC](https://discourse.julialang.org/t/better-documentation-for-properties-vs-fields/68173/3 "2021-09-15T01:48:49Z")

</div>

Yes, absolutely! Documentation PRs are always very welcome, especially from users who may be fairly new to Julia, since it’s often difficult to judge for contributors which parts new users struggle with the most and where our documentation could still be improved.

---

<div class="post-metadata">

**Author:** ![apo383](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/apo383/32/11272_2.png) [@apo383](https://discourse.julialang.org/u/apo383)\
**Post date:** [September 15, 2021, 3:09am UTC](https://discourse.julialang.org/t/better-documentation-for-properties-vs-fields/68173/4 "2021-09-15T03:09:55Z")

</div>

Yes, better documentation would be great, and especially the intent of properties could be explained more. And yes, the distinction should be documented, and I currently fail to understand it. I thought of properties as an abstraction of fields, allowing for exposing and hiding things, and providing a property interface where the underlying fields could be changed without breaking behavior or the user knowing. However, the abstraction doesn’t always make sense:

```julia
julia> struct Creature number end

julia> dog = Creature(1);

julia> getfield(dog, :number)
1

julia> getproperty(dog, :number)
1

julia> fieldnames(typeof(dog))
(:number,)

julia> propertynames(dog)
(:number,)

julia> propertynames(Creature)
(:name, :super, :parameters, :types, :names, :instance, :layout, :size, :ninitialized, :hash, :abstract, :mutable, :hasfreetypevars, :isconcretetype, :isdispatchtuple, :isbitstype, :zeroinit, :isinlinealloc, :has_concrete_subtype, :cached_by_hash)

```

`getfield` and `getproperty` are roughly parallel, but not so for `fieldnames` and `propertynames`. Years ago you could do `fieldnames(dog)` but that was deprecated for reasons I don’t recall. But why should it be fine to do `propertynames(dog)`, and why does `propertynames(typeof(dog))` do what it does? That would be helpful to have explained in the documentation.

---

<div class="post-metadata">

**Author:** ![nalimilan](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/nalimilan/32/147_2.png) [@nalimilan](https://discourse.julialang.org/u/nalimilan)\
**Post date:** [September 15, 2021, 4:02pm UTC](https://discourse.julialang.org/t/better-documentation-for-properties-vs-fields/68173/5 "2021-09-15T16:02:11Z")

</div>

> [@apo383](#):
>
> But why should it be fine to do `propertynames(dog)` , and why does `propertynames(typeof(dog))` do what it does? That would be helpful to have explained in the documentation.

This is because properties may vary across instances of a given type, contrary to fields which appear in the type definition. For example, `DataFrame` columns can be accessed using `getproperty`, and column names of course vary from one data frame to another.

This is indeed worth documenting.

---

<div class="post-metadata">

**Author:** ![nandoconde](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/nandoconde/32/19497_2.png) [@nandoconde](https://discourse.julialang.org/u/nandoconde)\
**Post date:** [September 15, 2021, 4:22pm UTC](https://discourse.julialang.org/t/better-documentation-for-properties-vs-fields/68173/6 "2021-09-15T16:22:17Z")

</div>

Alright then! I’m writing the issue and the PR 😃

---

<div class="post-metadata">

**Author:** ![apo383](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/apo383/32/11272_2.png) [@apo383](https://discourse.julialang.org/u/apo383)\
**Post date:** [September 15, 2021, 6:12pm UTC](https://discourse.julialang.org/t/better-documentation-for-properties-vs-fields/68173/7 "2021-09-15T18:12:12Z")

</div>

> [@nalimilan](#):
>
> properties may vary across instances of a given type

Indeed, properties are a pretty good abstraction, and I prefer `propertynames(dog)` anyway. I guess the leakier abstraction was with fields, hence `fieldnames(typeof(dog))`. So @nandoconde, perhaps the appropriate thing is flip the emphasis: `propertynames` could be referenced 8 times, and `fieldnames` only 4! Thanks for raising the point, I think this is well worth improving.

---

<div class="post-metadata">

**Author:** ![nandoconde](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/nandoconde/32/19497_2.png) [@nandoconde](https://discourse.julialang.org/u/nandoconde)\
**Post date:** [September 16, 2021, 9:38am UTC](https://discourse.julialang.org/t/better-documentation-for-properties-vs-fields/68173/8 "2021-09-16T09:38:57Z")

</div>

If anyone wants to peep in, I have submitted it!

[https://github.com/JuliaLang/julia/issues/42273](https://github.com/JuliaLang/julia/issues/42273)