Open joshlf opened 4 months ago
I have a scratchpad of name correspondences here: https://docs.google.com/spreadsheets/d/1o_ll7S3iW7xe3UdG_t8hzjBmUD-uRHXKyxZXJ7i1D2g/edit?usp=sharing
We do have some minor naming inconsistencies between Ref
and FromBytes
. For example, FromBytes::{mut_from_prefix,ref_from_prefix}
corresponds to Ref::new_from_prefix
. The pattern here, which holds for many other such methods, is that one drops the mut
/ref
and replaces it with new
.
This pattern does not apply to FromBytes::{mut_from,ref_from}
. The pattern suggests a correspondence to Ref::new_from
, but it actually corresponds to Ref::new
.
As a point of brevity: I wonder if we should drop the new_
prefixes. They're abundant and redundant — the fact that these are constructed a Ref
is already denoted by from
.
The placement of unaligned
and zeroed
in the Ref
names is awkward. Why new_slice_unaligned_from_prefix
and not new_unaligned_slice_from_prefix
(i.e., adjective preceding the noun)?
Also: When we add KnownLayout APIs in #996, we need to bikeshed their names too.
Re. the count-taking methods: Current contenders include _with_trailing_elements
and _with_count
. These result in identifiers of up to 39 characters long (mut_from_prefix_with_trailing_elements
) and 27 characters long (mut_from_prefix_with_count
), respectively.
Personally, I'm inclined towards the briefer option. I'd also argument that with_trailing_elements
is a misnomer; these methods don't consume trailing elements, they consume a count of the trailing elements.
For even more bevity, we could even do:
$ echo {,count_}{mut,ref}_from{,_prefix,_suffix} | tr ' ' '\n'
mut_from_prefix
mut_from_suffix
ref_from
ref_from_prefix
ref_from_suffix
count_mut_from
count_mut_from_prefix
count_mut_from_suffix
count_ref_from
count_ref_from_prefix
count_ref_from_suffix
The longest identifier here is only 22 characters long. Personally, I'm a little attached to having all of our identifiers on FromBytes
start with either ref
or mut
.
Discussed offline, and decided to go with xxx_with_elems
for methods that take a trailing slice element count.
Progress
FromBytes::ref_from_prefix
inconsistent withFromBytes::from_prefix_with_trailing_elements
?1210
with_trailing_elements
withwith_elems
in method names#[doc(hidden)]
pub
functions/methods - finalize naming or delete#[doc(hidden)]
and#[deprecated]
#[deprecated]
attributes were added)TODO(#871)
commentsRef::from
cause inference issues since Rust thinks it might beFrom::from
rather than inherent?1258
Ref::unaligned_from
tounaligned_from_bytes
1278
FromBytes::ref_from[_with_elems]
toref_from_bytes[_with_elems]
1278
FromBytes::read_from
toread_from_bytes
?TryFromBytes
methods for naming consistency w/FromBytes
methods1475
Ref
methods returnOption
s instead ofResult
s (ie, consistent with old signatures)?Details
In the same vein as #253, we should audit our API for:
Also see #284, the "Naming" section of #1095